Codex CLI のセットアップと AGENTS.md の書き方【ChatGPT アカウントで始める】

Codex CLI は OpenAI が提供するターミナル向けのコーディングエージェントです。ChatGPT のアカウントでログインでき、ローカルのリポジトリを読んでコードを書き、コマンドを実行します。

この記事では、インストールからログイン、最初のタスク実行までの手順と、Codex がプロジェクトのルールを理解するために読み込む AGENTS.md の書き方をまとめます。

前提条件

項目	内容
OS	macOS、Linux。Windows は WSL2 経由が案内されている
Node.js	npm でインストールする場合に必要(LTS 版)
アカウント	ChatGPT の有料プラン、または OpenAI API キー
Git	リポジトリ操作をさせるなら必須

インストール

npm または Homebrew でインストールします。

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

バージョンを確認します。

codex --version

ログイン

プロジェクトのディレクトリで codex を起動すると、初回にログイン方法を選ぶ画面が出ます。

cd path/to/project
codex

• ChatGPT アカウントでログイン: ブラウザが開き、ChatGPT にサインインします。プランに含まれる利用枠で使えます。
• API キーでログイン: 従量課金で使います。環境変数 OPENAI_API_KEY を設定するか、codex login --api-key で登録します。

codex login --api-key "sk-..."
codex login status   # ログイン状態の確認

最初のタスク

起動後の入力欄に、やりたいことを日本語で書きます。

このリポジトリの構成を説明して。テストの実行方法も教えて

Codex は必要なファイルを読み、必要ならコマンドを実行して答えます。ファイルの変更やコマンド実行の前に確認が入るかどうかは、承認モードとサンドボックスの設定で決まります。既定の設定はワークスペース内の書き込みを許可しつつ、外部への影響がある操作は確認する構成です。詳細は Codex CLI の approval mode と sandbox 設定の違い を参照してください。

AGENTS.md の役割と配置

Codex は起動時に AGENTS.md を探して読み込み、プロジェクトのルールとして扱います。AGENTS.md は Codex 専用ではなく、複数の AI コーディングツールが共通で読む形式として広まっています。

配置場所	用途
~/.codex/AGENTS.md	全プロジェクト共通の個人的な好み
リポジトリのルート AGENTS.md	チームで共有するプロジェクトのルール
サブディレクトリの AGENTS.md	そのディレクトリ配下にだけ適用するルール

複数ある場合は、ルートからカレントディレクトリに向かって順に読み込まれ、より深い階層のものが優先されます。

AGENTS.md のテンプレート

# プロジェクト概要
Express + TypeScript の REST API。DB は PostgreSQL(Prisma)。

## セットアップとコマンド
- 依存関係: `pnpm install`
- 開発サーバー: `pnpm dev`
- テスト: `pnpm test`(変更に関連するテストを必ず実行する)
- Lint / 型チェック: `pnpm lint && pnpm typecheck`
- マイグレーション: `pnpm prisma migrate dev`

## コーディング規約
- 関数は 50 行以内。超える場合は分割する
- エラーは `AppError` を throw し、握りつぶさない
- 外部 API の呼び出しは `src/clients/` に集約する
- `any` を使わない

## 変更してはいけないもの
- `prisma/migrations/` の既存ファイル
- `src/generated/`(自動生成)

## 作業の進め方
- 複数ファイルにまたがる変更は、先に方針を箇条書きで提示する
- テストが通らない状態で完了報告をしない
- コミットメッセージは Conventional Commits 形式

## PR を作るとき
- タイトルは 50 字以内
- 本文に「変更理由」「テスト方法」を書く

/init を実行すると、Codex がプロジェクトを調べて AGENTS.md の雛形を生成します。雛形はそのまま使わず、README を見れば分かる内容は削って、「見ただけでは分からない約束事」だけを残してください。

対話中に使う主なコマンド

コマンド	内容
/init	AGENTS.md の雛形を生成
/model	モデルと推論の深さを切り替える
/approvals	承認モードを切り替える
/status	現在の設定、モデル、トークン使用量を表示
/diff	現在の変更差分を表示
/clear	会話履歴をクリア

CLAUDE.md と併用する

Claude Code も使うチームでは、AGENTS.md と CLAUDE.md の両方が必要になります。内容を二重管理しないための方法は CLAUDE.md・AGENTS.md・GEMINI.md の違いと共通化テクニック を参照してください。設定ファイル(config.toml)によるモデルやプロファイルの切り替えは config.toml でモデルとプロファイルを切り替える で解説しています。

まとめ

• npm install -g @openai/codex または Homebrew で入れ、codex で起動して ChatGPT アカウントか API キーでログインする
• OPENAI_API_KEY が設定されていると API キーが優先されるので注意する
• AGENTS.md は ~/.codex/、リポジトリのルート、サブディレクトリの 3 階層で、深いものが優先される
• /init で雛形を作り、「見ただけでは分からない約束事」だけを残す