Codex CLI 0.31を使い倒す：設定と自走開発ベストプラクティス

Posted at 2025-09-09

はじめに

これまでClaude CodeをMax x20プランで使い倒してきましたが、CodeX CLIの改良されて使い勝手が上がったので並行して利用し、Code Xにresume機能が実装されたのを機に完全に乗り換えました。

OpenAI の Codex CLI は、リポジトリを「ワークスペース」として AI エージェント的に操作できるコマンドラインツールです。
0.30 以降で機能が増え、自走させてプロダクトの完成に辿り着けるのか？という観点で検証を行いました。
ここでは 設定方法と運用のベストプラクティスを中心にClaude Codeとの比較を交えてまとめます。

環境

Ubuntu 24.04.3 LTS (WSL2上)
Codex CLI 0.31.0
~/.codex/config.toml にプロファイルを作成

設定（config.toml）

# ~/.codex/config.toml

[profiles.readonly]
sandbox_mode = "read-only"

[profiles.build]
sandbox_mode = "workspace-write"

[profiles.unattended]
sandbox_mode = "workspace-write"

[projects."/home/devuser/work/CodeX/TEST/A"]
trust_level = "trusted"

profiles
- readonly: 設計や調査で安全に
- build: ワークスペース内の編集・実行を許可（PoC運用の基本）
- unattended: 短時間の全自動用（検証環境でのみ推奨）
projects…trust_level
- 指定パスを「信頼済み」にすると、編集や実行の承認確認が減る

サンドボックスと承認モード

Codex CLI は「どこまで自動で許可するか」をモードで制御します。

Read Only: 読み取り専用
Auto (デフォルト): ワークスペース内は自動、外部アクセスは承認が必要
Full Access: ネットワークやシステム操作も自動実行（危険なので基本使わない）

workspace-write にしても ネットワーク操作は既定で禁止 です。PoCなどで完全フルオートにしたい場合のみ、一時的に承認を出す運用。

resume/continue/history の現状

0.30で --resume / --continue / --history が入りましたが、ヘルプ未掲載で挙動は未成熟。
実際には codex --history でセッション一覧を出し、--resume で再開できる場合もあるが、フレークも報告されています。

履歴管理の課題（Claude Codeとの比較）

Codex CLI の履歴は 単一のストアに積まれる設計のようで、同じ環境で複数CLIを動かすと判別が難しい。
粒度も粗めで、Claude Code のように「会話＝ワークスペース」が直感的に結びつかない。
実務では以下の工夫が有効：
- セッション名をプロンプトで明示（例: SESSION:foo を出力やコミットに必ず残す）
- .codex/session.txt に開始/終了を記録させる
- ブランチ名やコミットメッセージに [SESSION:foo] を含める
将来の改善が待たれるが、現状では 「人間が名札をつける」運用が必須。

AGENTS.md の役割

Codex はリポ直下やサブディレクトリの AGENTS.md を読み、行動方針や禁止事項を理解する。
自走させたいなら AGENTS.md がほぼすべての鍵。

最低限おすすめする記述：

## Mission
ゴールと成功条件（テストがgreenになることなど）

## Environment
起動/テスト/ビルドの手順（makeやnpm scriptsに統一）

## Guardrails
禁止事項（例: 本番DB編集、外部API書き込み）

## Workflow
小さいタスク単位で diff → テスト → 実行 → レポート

## Deliverables
最低限必要な成果物（例: /health エンドポイント、README、E2Eテスト）

運用のベストプラクティス

GOALS.md を置く
- Definition of Done を明文化 → Codexに「ここを目指せ」と指示できる。
AGENTS.md でガイドラインを与える
- Mission/Guardrails/Workflowを明記。

Makefile に codex ターゲットを用意

codex:
	@codex --profile build    "Read and apply AGENTS.md (root→current). Confirm effective rules, then proceed."

→ 毎回一定のプロンプトを渡せる。

プロファイルを切り替えて自走度を調整
- readonly → 設計フェーズ
- build → 実装フェーズ
- unattended → 短時間のフルオート
無人運転は慎重に
- 検証環境限定で
- Gitでスナップショットを切ってから走らせる

`/status` 出力の比較（0.30 vs 0.31）

0.30 の例

/status
📂 Workspace
  • Path: ~/work/CodeX/bookB
  • Approval Mode: never
  • Sandbox: danger-full-access
  • AGENTS files: (none)

👤 Account
  • Signed in with ChatGPT
  • Login: ootakazuhiko@gmail.com
  • Plan: Pro

🧠 Model
  • Name: gpt-5
  • Provider: OpenAI
  • Reasoning Effort: Medium
  • Reasoning Summaries: Auto

📊 Token Usage
  • Session ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  • Input: 627113 (+ 13611904 cached)
  • Output: 68686
  • Total: 695799

0.31 の例

/status
📂 Workspace
  • Path: ~/work/CodeX/ae-framework
  • Approval Mode: never
  • Sandbox: danger-full-access
  • AGENTS files: (none)

👤 Account
  • Signed in with ChatGPT
  • Login: ootakazuhiko@gmail.com
  • Plan: Prokoko

🧠 Model
  • Name: gpt-5
  • Provider: OpenAI
  • Reasoning Effort: Medium
  • Reasoning Summaries: Auto

💻 Client
  • CLI Version: 0.31.0

📊 Token Usage
  • Session ID: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  • Input: 0
  • Output: 0
  • Total: 0

差分まとめ

Client セクション追加 → CLI バージョンが表示されるようになった
情報の構造化が改善 → Workspace / Account / Model / Client / Token Usage に整理
Session ID の扱いが見やすくなり、履歴管理との関連も強化された

まとめ

Codex CLI 0.30〜0.31 で プロファイル設定と AGENTS.md が整備され、自走PoCが現実的になった。
完全暗黙適用はまだ弱い → 起動時に「AGENTS.md を読んで従え」とプロンプトするのが実用的。
履歴管理は未成熟 → 複数セッションで混ざるため「名札をつける」運用が必要。
/status の改善で バージョン差分やSandbox状態を一目で確認できるようになった。

補足

この記事は PoC 検証のまとめです。挙動は今後のリリースで変わる可能性があります。
最新情報は GitHub の Issue/Releaseノートをチェックするのがおすすめです。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up