codex-config-optimizer

Codex CLI 最適化スキル

Codex CLI の設定最適化に関するルールと追跡情報です。

1. 設定ファイルの場所

設定は、Nix（programs.codex home-manager モジュール）を使って宣言的に管理します。

信頼できる情報源：

• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/codex-cli.nix
• @~/ghq/github.com/i9wa4/dotfiles/nix/home-manager/agents/

配置先	ソース	管理元
~/.codex/config.toml	アクティベーションスクリプトによって生成	codex-cli.nix
~/.codex/AGENTS.md	AGENTS.md + インライン化された rules/*.md から生成	instruction-artifacts.nix
~/.codex/rules/	拒否対象の Bash ポリシーから default.rules を生成	codex-cli.nix
~/.codex/hooks.json	フック設定を生成	codex-cli.nix
~/.codex/scripts/	codex-* スクリプトと共通の拒否パターンをシンボリックリンク	codex-cli.nix
~/.codex/skills/	複数の flake 入力 + ローカル	agent-skills.nix
MCP サーバー	nix/home-manager/agents/mcp-servers.nix	codex-cli.nix

2. 設定管理

静的設定（モデル、分析、機能、MCP サーバー）は、codex-cli.nix の Nix 属性として定義されています。信頼されたプロジェクトは、home-manager switch の実行時に fd で動的に検出され、config.toml に追加されます。

フックも codex-cli.nix で宣言されています。実行時スクリプトは nix/home-manager/agents/scripts/codex-* にあり、切り替え時に ~/.codex/scripts/ に配置されます。

設定を更新するには、nix/home-manager/agents/codex-cli.nix を編集して再ビルドしてください。

3. リリースの取得

3.1. ローカルバージョンの検出

必ず最初にインストール済みのバージョンを検出してください。

codex --version

これにより、ローカルにインストールされているバージョン（例：codex-cli 0.113.0）が返されます。 すべてのリリース分析は、このバージョン以下を対象にする必要があります。 ローカルのインストールより新しいバージョンの機能や変更を報告しないでください。

3.2. GitHub からの取得

FILE=$(mkmd --dir tmp --label output)
gh api repos/openai/codex/releases --jq '.[0:10]' > "$FILE"

次に、以下を使ってローカルバージョンまでのエントリーを抽出します。

jq '.[] | select(.tag_name == "rust-v<LOCAL_VERSION>") | {tag_name, body}' "$FILE"

4. CHANGELOG の操作

重要：以下のすべての操作は、ローカルにインストールされているバージョンを対象とします。 codex --version より新しいバージョンのリリースエントリーは無視してください。

4.1. 最新リリースの概要

1. codex --version でローカルバージョンを検出します
2. 上記のコマンドでリリースを取得します
3. rust-v<local-version> のリリースエントリー（最初のエントリーではありません）を抽出します
4. 変更を以下のように分類します：
   • 新機能（Added）
   • バグ修正（Fixed）
   • 改善（Improved/Changed）
   • 破壊的変更
5. 簡潔な説明を添えて日本語で提示します

4.2. バージョン間の差分

1. codex --version でローカルバージョンを検出します
2. 開始バージョンをユーザーに尋ねます（終了バージョンはデフォルトでローカルバージョンです）
3. 開始バージョンからローカルバージョンまで（両端を含む）のすべてのリリースを抽出します
4. 累積した変更を要約します
5. 破壊的変更と非推奨項目を強調します

4.3. 破壊的変更の検出

1. codex --version でローカルバージョンを検出します
2. ローカルバージョンまでのリリースで、breaking、removed、 deprecated、changed（動作の変更）を検索します
3. 影響を受けるコマンドとオプションを一覧表示します
4. 移行方法を提示します

5. 設定カテゴリ

カテゴリ	例
モデル	model、model_reasoning、model_reasoning_effort
動作	approval_mode、sandbox、network_access
表示	notify、tui.notifications_method
シェル	shell_environment_commands
フック	features.codex_hooks、hooks.json、scripts/codex-*
履歴	history、project_doc_max_bytes
機能	features.skills、features.web_search_request
無効化	disable_response_storage、hide_agent_*
アナリティクス	analytics.enabled、feedback.enabled

6. フックのガイダンス

• 必須：hooks.json の動作に依存する前に、features.codex_hooks = true を設定してフックを有効にしてください
• 必須：Codex のホームレベルのフックは、意図的にリポジトリローカルで上書きする必要がある場合を除き、 nix/home-manager/agents/codex-cli.nix に保持してください
• 必須：Codex のフックスクリプトは、 nix/home-manager/agents/scripts/codex-* の下に配置してください
• 必須：Bash の拒否ポリシーを別途 Codex 専用コマンドリストとして手動管理せず、 denied-bash-commands.nix を SSOT として再利用してください
• 必須：共有の Bash 拒否理由は修復を促す内容にしてください。拒否されたことを伝えるだけでなく、エージェントが次に何をすべきかを示してください
• 必須：現時点では、Codex の PreToolUse と PostToolUse は Bash のみを対象とするものとして扱ってください
• 必須：PostToolUse の Bash フックはフィードバック専用にしてください。コマンドはすでに実行済みなので、擬似的な強制ではなく、簡潔な修正方法を提示するために使用してください
• 禁止：Codex が現在 Write|Edit|NotebookEdit をインターセプトすると主張しないでください。これらのマッチャー例は正規表現として有効ですが、現在の Codex ランタイムには一致しません
• 禁止：PreToolUse でサポートされていない permissionDecision: "ask" / "allow"、updatedInput、additionalContext フィールドに依存しないでください。現在のランタイムはこれらを解析しますが、フェイルオープンになります
• 注：公式ドキュメントによると、現在サポートされているイベントは SessionStart、PreToolUse、PostToolUse、UserPromptSubmit、Stop です
• 注：公式ドキュメントによると、複数の hooks.json ファイルにある一致するフックはすべて実行され、同じイベントに一致するコマンドフックは並行して起動します
• 注：現在の Codex で Claude の PreCompact に最も近いのは Stop です。完全な同等性の証明としてではなく、軽量な引き継ぎ情報の永続化に使用してください

7. AGENTS.md の設計ガイドライン

• 必須：ペルソナと基本ガイドラインのみに焦点を当ててください
• 必須：Claude Code と Codex CLI の両方に対応する指示にしてください
• 禁止：ツール固有の構文（例：Claude Code の TodoWrite）を含めないでください

8. 最適化チェックリスト

AGENTS.md または config.toml を編集するときは、以下を確認してください。

• ペルソナの定義は簡潔ですか？
• 基本ルールは常に本当に必要ですか？
• 詳細な説明を skills/ に移動できますか？
• config.toml では適切な approval_mode が使用されていますか？
• 共有の Bash 拒否メッセージは、拒否を伝えるだけでなく、安全な次の手順を示していますか？
• Codex のフックの制限（ツール前後のフックは Bash のみ）が正直に記載されていますか？
• PostToolUse は強制ではなく、決定論的な Bash フィードバックに限定されていますか？
• フックの状態は hooks.json と scripts/codex-* に正しく分けられていますか？

9. 最適化の追跡

最終確認済みの Codex CLI バージョン：v0.117.0 (2026-03-30)

9.1. 適用済みの最適化

• 共有の AGENTS.md とインライン化したルールの Markdown から AGENTS.md を生成
• skills/ を Claude Code のスキルにシンボリックリンク
• 拒否する Bash ポリシーから default.rules を生成
• ホームレベルの Codex フックを有効化：UserPromptSubmit、SessionStart、PreToolUse（Bash のみ）、PostToolUse（Bash のみ）、Stop
• Claude Code と Codex CLI のフックで共有の deny-bash パターンを再利用
• 共有の deny-bash に関する説明を、単なる拒否から Claude Code と Codex CLI の両方に向けた修正ガイダンスに強化
• Codex の UserPromptSubmit に時刻、ロール、cwd、git コンテキストを追加
• Stop と SessionStart による軽量な Codex の引き継ぎ情報の永続化
• model_auto_compact_token_limit = builtins.floor (codexContextWindow * 0.7) により、70% で自動コンパクト化（gpt-5.x の 272k ウィンドウでは 190,400 トークン）
• tui.terminal_title = [] で Codex によるターミナルタイトルの書き込みを無効化し、tmux の pane_title をロール識別用に確保（v0.117.0）

9.2. 検討事項

• 必要に応じて prompts/ から ../claude/commands/ へのシンボリックリンクを作成
• config.toml を自動生成する generate-config.sh を作成
• MCP サーバーの統合を評価（AWS docs MCP など）
• プランモード（/plan）- 安定し、デフォルトで有効化済み（v0.94.0）
• command_attribution = "disable" - 共著者の帰属表示を無効化（v0.103.0）
• PostToolUse Bash のフィードバックヒューリスティクス - 新たなリポジトリの失敗パターンが繰り返されても、対象範囲を狭く、決定論的に保つ
• code_mode の実験的機能 - 独立したコーディングワークフロー。安定化を注視（v0.114.0）
• バンドルされたシステムスキルの設定切り替えを無効化 - カスタムスキルで十分な場合、より軽量なセッションに役立つ（v0.114.0）
• 権限プロファイルの設定言語 - config.toml でファイルシステム／ネットワークのサンドボックスポリシーを分割し、より細かく制御（v0.113.0）
• サブエージェントのサポート - マルチエージェント機能が安定化（v0.115.0）。Nix のビルド時に subagents/*.md から .toml エージェントを自動生成（codex-cli.nix）
• openai_base_url の設定オーバーライド - カスタム API エンドポイント（v0.115.0）
• Smart Approvals guardian - 承認の手間を軽減するため、レビュー依頼を guardian サブエージェント経由で処理（v0.115.0）

9.3. 採用しない項目

• personality 設定 - デフォルト（「friendly」）を維持。変更しても利点なし
• log_dir 設定 - デフォルトのログ保存先で問題なし
• tui.notifications_method - デフォルトを維持
• CLAUDE_CODE_DISABLE_CRON 環境変数 - Codex CLI では該当なし
• approval_policy: on-failure - 非推奨（v0.102.0）。設定では未使用
• Write|Edit のような PreToolUse／PostToolUse のマッチャーパターン - 現在の Codex ランタイムが出力するのは Bash のみのため、これらの設定は現状を誤解させる
• PreToolUse の permissionDecision: "ask"／"allow" と updatedInput - 現在のランタイムは解析するものの、適用しない
• Bash 修正フックの PostToolUse における判定／ブロックのセマンティクス - Codex が生のコマンド結果を確認できるよう、フィードバックのみに限定
• AfterToolUse フック - 文書化されたフックエンジンに置き換え済み
• smart_approvals - デフォルトの動作を維持（v0.93.0）

9.4. バージョンに関する注意事項

• v0.117.0：/title のターミナルタイトル選択機能がクラシックと app-server TUI の両方で動作するようになり、プラグインが正式なワークフローの一部となりました。app-server TUI がデフォルトで有効になり、従来の artifact、read_file、grep_files ハンドラーが削除されました
• v0.116.0：確認時点でのローカルインストール済みバージョンです。公式のフックドキュメントでは、引き続きフックが実験的機能とされ、現在サポートされているイベントと制限が記載されています。https://developers.openai.com/codex/hooks
• v0.115.0：view_image によるフル解像度の画像検査、セルをまたいで永続化する codex.cwd／codex.homeDir が js_repl に追加、リアルタイム WebSocket 文字起こしモードと v2 ハンドオフ、Python SDK を使った v2 app-server ファイルシステム RPC、レビューの振り分けを行う Smart Approvals ガーディアン・サブエージェント、フォールバック付きの Responses API によるツール検索、マルチエージェント機能の安定化、wait_agent ツールの名前変更、Linux サンドボックスで bubblewrap をデフォルトに設定、openai_base_url による設定の上書き
• v0.114.0：実験的なコードモード（分離されたコーディング）、フックエンジン（SessionStart／Stop）、app-server WebSocket 用のヘルスエンドポイント（/readyz／/healthz）、バンドルされたシステムスキルを無効にする設定、ターンの継続性を保つハンドオフのトランスクリプトコンテキスト、カテゴリラベル付きの $ メンション選択機能、Linux tmux のセグメンテーション違反を修正、ターンをまたいだ承認の保持、Python SDK v2 のスキーマ基盤
• v0.113.0：request_permissions ツール（実行時の権限リクエスト）、プラグインマーケットプレイスと厳選されたプラグインの発見・アンインストール、TTY／PTY 対応の app-server ストリーミング実行、Web 検索ツールの完全な設定、権限プロファイルの設定言語、画像生成結果の cwd への保存、ログ用 SQLite DB、winget の自動更新
• v0.112.0：プラグインを直接参照する @plugin メンション、権限プロファイルのターンごとのサンドボックスへの統合、JS REPL のバインディング永続化を修正、SIGTERM による正常なシャットダウン、bubblewrap の userns 強化、macOS Seatbelt の改善
• v0.111.0：高速モードがデフォルトで有効になり、TUI に高速／標準モードが表示されるようになりました。js_repl でローカルの .js／.mjs ファイルをインポート可能に。セッション開始時にモデルへプラグインを通知。構造化されたリクエスト／レスポンス形式による app-server v2 MCP エリシテーション
• v0.110.0：プラグインシステム（設定またはマーケットプレイスからのスキル／MCP／アプリコネクター）、永続化される /fast 切り替え、承認プロンプト付きのマルチエージェント TUI フロー、ワークスペース単位のメモリ書き込み、Windows インストーラー
• v0.107.0：スレッドをサブエージェントに分岐、リアルタイム音声デバイスの選択、マルチモーダルなカスタムツール出力、設定可能なメモリ（codex debug clear-memories）
• v0.104.0：WebSocket プロキシ用の WS_PROXY／WSS_PROXY 環境変数、app-server の ConfigChange フック、コマンド承認 ID の連携
• v0.103.0：command_attribution 設定によるコミットの共同作成者表記、一覧表示のアプリ詳細を拡充
• v0.102.0：TUI 履歴を含む権限フローの統一、サンドボックスの読み取りアクセスを許可するスラッシュコマンド、カスタマイズ可能なマルチエージェントの役割、model/rerouted 通知、approval_policy: on-failure の非推奨化
• v0.101.0：メモリとモデル解決のバグ修正
• v0.100.0：実験的な JS REPL ランタイム、メモリ用スラッシュコマンド（/m_update、/m_drop）、ReadOnlyAccess サンドボックスポリシー、AfterToolUse フック
• v0.99.0：TUI フッターを設定する /statusline コマンド、シェルコマンドが実行中のターンを中断しないよう変更、GIF／WebP 画像のサポート、AfterToolUse フックの追加、セキュリティ修正（RUSTSEC-2026-0009）
• v0.98.0：GPT-5.3-Codex モデルを導入、ステアモードがデフォルトで安定版に（Enter で送信、Tab でキューに追加）
• v0.97.0：MCP／アプリツールの「許可して記憶」、スキルのライブ更新、/debug-config スラッシュコマンド、設定可能な log_dir
• v0.96.0：Windows 以外のすべてのプラットフォームで unified_exec を有効化
• v0.95.0：~/.agents/skills から個人スキルを読み込み、/plan が引数と画像を受け付けるよう変更、並列シェルツール、CODEX_THREAD_ID 環境変数を注入
• v0.94.0：プランモードがデフォルトで有効に、personality 設定が安定版に（デフォルト：フレンドリー）、.agents/skills からスキルを読み込み

10. 応答形式（CHANGELOG）

# Codex CLI vX.X.X 更新内容

## 新機能
- [機能名]: [説明]

## バグ修正
- [修正内容]

## 改善
- [改善内容]

## 破壊的変更
- [影響を受ける機能と移行方法]

---
Source: https://github.com/openai/codex/releases

11. 重要な注意事項

• Codex CLI の変更履歴は CHANGELOG.md ではなく、リリースページにあります
• リリースノートを取得するには、GitHub releases API を使用してください
• 参照するバージョンを必ず明記してください
• 公式リリースページがある場合は、そちらにリンクしてください

12. 参考リンク

• Codex CLI：https://github.com/openai/codex
• Codex hooks のドキュメント：https://developers.openai.com/codex/hooks