🐡

Codex CLI 完全ガイド：全体像

に公開
AI
aiコーディング
Vibe Coding
Codex
Codex CLI
tech

はじめに

本記事では、OpenAI Codex リポジトリ（codex/）の構造と各コンポーネントの役割、設定・サンドボックス・MCP 連携・テストフローに至るまでを詳細に整理します。実際に参照したソースコードを交え、どのディレクトリが何を担当しているかを明確にすることを目的としています。

⚠️ リポジトリは頻繁に更新されます。記載内容は記事執筆時点（2025-10-01）の情報です。最新の実装は該当ファイルを直接確認してください。

1. リポジトリ全体構成と注目ポイント

codex/
├── codex-rs/         # Rust 実装（Cargo ワークスペース）
├── codex-cli/        # 旧 TypeScript CLI（レガシー）
├── sdk/typescript/   # Web/API 用 TypeScript SDK
├── docs/             # 設定・運用ドキュメント
├── scripts/          # ビルド／リリース補助スクリプト
├── AGENTS.md         # コントリビューター向けガイド
└── …

1.1 codex-rs/ Rust ワークスペース

codex-rs/Cargo.toml を見ると 25 以上のクレートが並ぶ大規模なワークスペースです。代表的なものを挙げると：

クレート パス 役割 チェックすべきファイル
codex-core codex-rs/core/ 会話エンジン、サンドボックス制御、MCP 管理など中核ロジック src/codex.rs, src/mcp_connection_manager.rs, src/protocol/
codex-cli（Rust） codex-rs/cli/ codex マルチツールの CLI エントリポイント src/main.rs, src/login.rs, src/mcp_cmd.rs
codex-tui codex-rs/tui/ Ratatui ベースの TUI src/app/, styles.md, tests/
codex-exec codex-rs/exec/ ヘッドレス CLI (codex exec) src/cli.rs, src/lib.rs
codex-mcp-client codex-rs/mcp-client/ MCP クライアント src/mcp_client.rs
codex-mcp-server codex-rs/mcp-server/ Codex を MCP サーバーとして動かす実験実装 src/lib.rs
codex-login codex-rs/login/ 認証フロー src/lib.rs
codex-common codex-rs/common/ CLI 共通ヘルパー (CliConfigOverrides 等) src/config_override.rs, approval_mode_cli_arg.rs
codex-protocol codex-rs/protocol/ イベントやサンドボックスポリシー定義 src/protocol.rs
linux-sandbox/process-hardening codex-rs/linux-sandbox/ 等 Seatbelt / Landlock 等サンドボックス実装 src/landlock.rs, src/lib.rs

1.2 codex-cli/（TypeScript 版）

  • 旧 CLI の実装が残っており README.md でレガシー扱い。
  • bin/codex.js がエントリ。scripts/ に npm パッケージ化の補助スクリプト。
  • npm 配布 (codex-cli/scripts/build_npm_package.py) や Dockerfile を読むと旧リリースフローが把握できます。

1.3 sdk/typescript/

  • Codex Web/API 向け SDK。
  • package.json に tsup、eslint、jest などが記載され、src/ に実装、tests/ に Jest テスト。

1.4 ドキュメント・スクリプト

  • docs/ に config.md、sandbox.md、advanced.md、authentication.md、contributing.md など。
  • scripts/ にはリリース (create_github_release.sh)、ネイティブ依存取得 (install_native_deps.py)、デバッグ補助ツールなど。

2. コマンド別アーキテクチャ

2.1 codex（対話型 TUI）

  1. codex-rs/cli/src/main.rs の MultitoolCli が CLI 引数を解析。
  2. サブコマンドが無い場合、codex_tui::run_main を呼び出して RatUI を起動。
  3. UI コンポーネントは codex-rs/tui/src/app/ に構造化。styles.md でカラールールと UI ガイドラインを解説。
  4. テキスト整形 (line_utils.rs)、折り返し (wrapping.rs) などのユーティリティも整備。
  5. スナップショットテスト（cargo test -p codex-tui → cargo insta）で UI 変更を検証。

2.2 codex exec（ヘッドレス）

  • CLI 定義：codex-rs/exec/src/cli.rs
  • 実処理：codex-rs/exec/src/lib.rs

run_main 序盤で承認ポリシー AskForApproval::Never を強制し、ヘッドレス環境で承認ダイアログを挟まず処理を進めます。

// codex-rs/exec/src/lib.rs
let overrides = ConfigOverrides {
    ...
    approval_policy: Some(AskForApproval::Never),
    sandbox_mode,
    cwd: cwd.map(|p| p.canonicalize().unwrap_or(p)),
    ...
};

ログレベルは RUST_LOG、JSON 出力は #[arg(long = "json", alias = "experimental-json")] で定義。MCP の初期化は codex-rs/core/src/mcp_connection_manager.rs に委譲されます。

2.3 codex login/logout

codex-rs/cli/src/login.rs に ChatGPT / API キー認証・ステータス確認・デバイスコードフロー（実験）が実装されています。

2.4 codex mcp

codex-rs/cli/src/mcp_cmd.rs に MCP サーバー管理 CLI。list、get、add、remove を通じて config.toml の [mcp_servers] を操作します。

2.5 codex debug seatbelt/landlock

サンドボックス挙動を確認する支援コマンド。codex-rs/cli/src/lib.rs に Seatbelt（macOS）／Landlock（Linux）のラッパーがあり、指定コマンドをサンドボックス下で実行します。

2.6 codex apply / codex cloud

  • codex apply: Codex Cloud の差分適用。codex-rs/chatgpt/src/apply_command.rs
  • codex cloud: Cloud タスクの RatUI。codex-rs/cloud-tasks/src/

3. サンドボックスと承認ポリシー

3.1 サンドボックスモード

codex-rs/protocol/src/protocol.rs の SandboxPolicy より：

pub fn new_workspace_write_policy() -> Self {
    SandboxPolicy::WorkspaceWrite {
        writable_roots: vec![],
        network_access: false,
        exclude_tmpdir_env_var: false,
        exclude_slash_tmp: false,
    }
}
  • ReadOnly: 読み取り専用。
  • WorkspaceWrite: cwd と TMP に書き込み可。ネットワークは false（必要に応じ -c で true に）。
  • DangerFullAccess: フルアクセス。

3.2 承認ポリシー

codex-rs/common/src/approval_mode_cli_arg.rs で定義。--ask-for-approval により untrusted、on-failure、on-request、never を選択。

4. MCP（Model Context Protocol）

4.1 MCP クライアント

codex-rs/mcp-client/src/mcp_client.rs が stdio / HTTP で MCP サーバーと通信します。

  • Initialize → ListTools → CallTool の流れをラップ。
  • タイムアウト時には request timed out エラー（codex-rs/mcp-client/src/mcp_client.rs:224）。
  • DEFAULT_ENV_VARS で MCP サーバーに継承される環境変数を定義。

4.2 MCP サーバー

codex-rs/mcp-server/ は Codex を MCP サーバーとして起動する実験的実装。

4.3 MCP 設定

~/.codex/config.toml の [mcp_servers] で command、args、startup_timeout_sec などを設定。CLI から -c mcp_servers.<name>.startup_timeout_sec=30 のように上書き可能。

5. 設定ファイルと CLI オーバーライド

5.1 CliConfigOverrides

codex-rs/common/src/config_override.rs の CliConfigOverrides が -c key=value を解析し、TOML として適用します。

5.2 docs/config.md

config.toml の全文例と各項目の詳説。

5.3 プロファイル

[profiles.<name>] でプリセット化。CLI の --profile で切り替えます。

6. ビルド・テスト・スナップショット

種別 コマンド 補足
フォーマット just fmt Rust 全体の rustfmt。
Lint just fix -p <crate> Clippy。共有クレートを変更した場合はワークスペース全体で。
Rust テスト cargo test -p codex-tui 等 クレートごとに実行。共通ロジック変更時は cargo test --all-features。
Snapshot cargo test -p codex-tui → cargo insta pending-snapshots → cargo insta accept RatUI の UI 変更を検証。
TypeScript pnpm install && pnpm test CLI / SDK の Jest テスト。

docs/contributing.md には開発フローや CLA 署名手順も記載されています。

7. codex exec + MCP の注意点（実例）

ヘッドレス実行で MCP を利用する際は以下に注意：

  1. codex exec は承認ポリシー Never を強制 → ネットワーク遮断。
  2. Workspace Write サンドボックスでは cwd／TMP 以外に書き込めない。
  3. uvx／npx がリモート依存を取得 → ネットワーク許可とキャッシュ書き込みが必要。
  4. codex_core::mcp_connection_manager のログは info! だが ERROR 風に見える。

権限調整例（詳細は「codex exec での MCP 起動エラーと対処法」を参照）：

RUST_LOG=warn,codex_core::mcp_connection_manager=off \
  codex exec \
    --experimental-json \
    --sandbox workspace-write \
    -c 'sandbox_workspace_write={network_access=true,writable_roots=["/path/to/.cache","/path/to/.uv"]}' \
    -c mcp_servers.serena.startup_timeout_sec=30 \
    --cd "/path/to/workspace" \
    resume <SESSION_ID> "こんにちは"

8. クイックスタート（Codex CLI の基本利用）

以下は、初回利用時の最小手順です。

  1. インストール（npm または Homebrew）
    npm install -g @openai/codex
# または
brew install codex
  2. ログイン（ChatGPT プラン推奨）
    codex
# TUI が開いたら「Sign in with ChatGPT」を選択
    ヘッドレス環境では codex login --api-key で API キーを設定可能。
  3. 設定確認
    ls ~/.codex
cat ~/.codex/config.toml
  4. 対話モード
    codex "README を要約して"
  5. ヘッドレス実行（例：MCP なし）
    codex exec --experimental-json -- cd ./project "テストを実行して"
  6. MCP を使う場合
    codex mcp add serena -- serena start-mcp-server --context codex
codex exec -c 'sandbox_workspace_write={network_access=true}' -- cd ./project "MCP で解析"

docs/getting-started.md と docs/config.md を併読すると、よりスムーズに利用できます。

9. 今後のシリーズ予定

「Codex CLI 完全ガイド」シリーズでは以下のテーマを予定しています。

# タイトル（仮） 概要
1 全体像（本記事） リポジトリ構造・主要クレート・設定方針の俯瞰。
2 codex exec 徹底解説 ヘッドレス運用、承認ポリシー、サンドボックス、MCP 連携、ログ制御。
3 サンドボックス＆セキュリティハードニング Seatbelt/Landlock の内部と CLI からの指定方法、危険操作時の注意点。
4 MCP 実践ガイド mcp_connection_manager の内部、MCP サーバー設定、トラブルシューティング。
5 TUI 開発とスナップショットテスト Ratatui UI の構造、cargo insta 運用、スタイルガイド。
6 設定ファイル／プロファイル最適化 config.toml の詳細、CliConfigOverrides の活用、プロファイル運用。
7 Codex Cloud 連携 codex cloud、codex apply、クラウドタスクの実務導入例。
8 TypeScript SDK 活用 sdk/typescript を使った API 連携、Node.js との統合。

随時内容を見直しつつ、各回でコード抜粋と実践的なユースケースを紹介する予定です。

10. まとめ

  • codex-rs ワークスペースが Codex CLI の本体。core と cli の連携を押さえると全体像が掴めます。
  • codex exec などヘッドレス運用では、サンドボックスと MCP 設定を調整することが重要です。
  • ドキュメント (docs/) とソースコードを突き合わせることで挙動の理解が深まります。
  • 変更前には just fmt、cargo test、cargo insta 等の基本セットを実行し、スナップショット差分も確認しましょう。

今後のシリーズ記事でより詳細な実装解説と運用ノウハウを提供していきます。まずは本記事を起点に、興味のあるトピックから順に読み進めてください。

Discussion