# Codex 完全チュートリアル

> **最終確認**：2026-09-18 · 📄 公式ドキュメント準拠（Codex CLI v0.155.0、2026-09-17 公開） · 5.4 の profile の挙動は別途自社環境で実測済み（✅ codex-cli 0.155.0、独立 HOME、モデルへのリクエストなし）

## 概要

| 項目 | 内容 |
|---|---|
| 利用できるモデル | GPT ✅（Responses 系統）· Claude ❌ · 中国系モデル ❌（Responses 系統は非対応）· Gemini ❌ |
| プロトコルと Base URL | OpenAI Responses：config.toml に `base_url = "https://api.qcode.cc/openai"` + `wire_api = "responses"` |
| 設定場所 | `~/.codex/config.toml`（Windows は `%USERPROFILE%\.codex\`） |
| 公式ドキュメント | [openai/codex](https://github.com/openai/codex) |

> 📖 Codex の `base_url` が Claude の `ANTHROPIC_BASE_URL` と違うのはなぜ？`/openai` と `/openai/v1` の違いは？ [エンドポイントと API パス](../getting-started/endpoints-and-api-paths) を参照。

本文は中国の開発者向けの **Codex CLI 完全チュートリアル**で、ゼロからOpenAI Codex CLIのインストール、設定、使用方法をご案内し、QCode.ccを通じて低コスト・低レイテンシーのAIプログラミング体験を提供します。AIプログラミングツールを初めて使う方も、Claude Codeを使用している方で新しいツールを試してみたい方も、ぜひご覧ください。

---

## 一、Codex の紹介

### OpenAI Codex CLI とは？

[Codex CLI](https://github.com/openai/codex) は、OpenAI が提供する**オープンソースのコマンドラインAIプログラミングアシスタント**（Apache 2.0 ライセンス）で、Rust で書かれており、ターミナルで直接実行できます。以下のことができます：

- コードリポジトリを**読み取り、理解**する
- ファイルを**編集**して新しいコードを生成する
- コマンドを**実行**する（テスト実行、依存関係インストールなど）
- タスクが完了するまで**自律的に反復**する

Codex の核心理念は**自律型エージェント（Autonomous Agent）**です：タスクを記述すると、Codex がサンドボックス内で自律的に完了させ、最後にあなたが結果をレビューします。これは Claude Code の**対話型コミュニケーション**スタイルと補完関係にあります。

### Codex の発展の歴史

「Codex」という名前は、OpenAI のプロダクトラインで何度も変遷を遂げてきました：

- **2021年**：最初の Codex は GPT-3 のコードファインチューニング版で、GitHub Copilot に動力を提供
- **2024年**：OpenAI は Codex ブランドを復活させ、クラウド非同期 AI プログラミングエージェントを導入
- **2025-2026年**：Codex CLI は成熟したローカルコマンドラインツールに発展し、Rust で書き直され、MCP、Skills、マルチエージェントなどの高度な機能をサポート

現在の Codex はマルチインターフェース製品です：**CLI コマンドラインツール**（本文の重点）、**macOS デスクトップアプリ**、**IDE プラグイン**、ChatGPT に統合された**クラウドエージェント**を含みます。QCode.cc を通じて使用するのは CLI バージョンです。

### Codex と Claude Code の主な違い

| ディメンション | Codex CLI | Claude Code |
|------|-----------|-------------|
| 実行スタイル | 自律実行、完了後に結果を交付 | 対話型コミュニケーション、段階的に確認 |
| オープンソース | 完全オープンソース（Apache 2.0） | オープンソースではない |
| 記述言語 | Rust（起動が速く、リソース使用量が低い） | TypeScript |
| サンドボックスセキュリティ | 内蔵 Landlock/seccomp サンドボックス | 権限確認のプロンプト |
| 命令ファイル | `AGENTS.md` | `CLAUDE.md` |
| クラウドエージェント | サポート（ChatGPT 内蔵） | サポートなし |

簡単に言えば：**Codex は「丸投げタスク」に強く**（明確な要件を与えて、最後まで走らせ切る）、**Claude Code は「ペアプログラミング」に強い**（議論しながら修正、探索的タスクに適している）。両方を組み合わせて使うのがベストです。

### なぜ QCode.cc を通じて Codex を使うのか？

Codex CLI はデフォルトで OpenAI API Key または ChatGPT サブスクリプションが必要ですが、中国本土には2つの問題があります：

1. **ネットワークに到達不可**：OpenAI API には直接アクセスできない
2. **コストが高い**：公式 GPT-5.3-Codex のトークン価格は低くない

QCode.cc を通じて、次のことができます：

- **グローバル多拠点への低レイテンシーアクセス**（`api.qcode.cc` グローバルルーティング / `us` / `eu` / `asia` フォールバック、CN ユーザーは `asia.qcode.cc` 推奨）、VPN や自作プロキシ不要
- **最大80%のコスト削減**、公式価格と比較して大幅に節約
- **Claude Code と Codex がプランのクォータを共有**、一つのプランで両方のツールを使用可能
- **マルチノード利用可能**（深セン直接接続 + グローバルルーティング）、接続安定性を保障

---

## 二、Codex CLI のインストール

### システム要件

インストールする前に、環境が以下の条件を満たしていることを確認してください：

- **オペレーティングシステム**：macOS 12+、Ubuntu 20.04+、Windows 10+（WSL2 使用推奨）
- **Node.js**：v22 LTS 以上（npm インストール方式が必要な場合）
- **Git**：2.x 以上（Codex はコードリポジトリを感知するために Git が必要）
- **ディスク容量**：約200MB（npm 依存関係を含む）

### 方法1：npm インストール（推奨）

これはすべてのオペレーティングシステムに通用的で最も一般的なインストール方法で：

```bash
npm install -g @openai/codex
```

> **ヒント**：権限問題が発生した場合、macOS/Linux ユーザーは `sudo` を追加するか、[nvm](https://github.com/nvm-sh/nvm) を使用して Node.js を管理することで権限問題を回避できます。

> **中国ユーザー向け**：npm のダウンロード速度が遅い場合は、淘宝mirrorを使用できます：
> ```bash
> npm install -g @openai/codex --registry=https://registry.npmmirror.com
> ```

### 方法2：Homebrew インストール（macOS）

macOS ユーザーは Homebrew を通じてインストールすることもできます：

```bash
brew install --cask codex
```

Homebrew の利点は、依存関係を自動的に管理し、更新してくれることです。

### 方法3：バイナリを直接ダウンロード（上級者向け）

[GitHub Releases](https://github.com/openai/codex/releases) ページから対応するプラットフォームのプリコンパイル済みバイナリファイルをダウンロードし、`PATH` ディレクトリに入れます。この方法は Node.js に依存しません。

```bash
# 例：Linux x64 バージョンをダウンロードしてインストール
wget https://github.com/openai/codex/releases/latest/download/codex-linux-x64
chmod +x codex-linux-x64
sudo mv codex-linux-x64 /usr/local/bin/codex
```

### インストールを確認

```bash
codex --version
```

バージョン番号が出ればインストール成功です。このページの数字を「いまの最新」だと思わないでください。正本は [GitHub Releases](https://github.com/openai/codex/releases) と [npm `@openai/codex`](https://www.npmjs.com/package/@openai/codex) です。本機は `codex --version` で確認します。

### シェル自動補完の設定（オプション）

Codex はシェル自動補完をサポートし、コマンドを入力時に `Tab` を押すとプロンプトが表示されます：

```bash
# Zsh ユーザー
echo 'eval "$(codex completion zsh)"' >> ~/.zshrc
source ~/.zshrc

# Bash ユーザー
echo 'eval "$(codex completion bash)"' >> ~/.bashrc
source ~/.bashrc
```

> Zsh が `command not found: compdef` と表示した場合、`eval` の前に `autoload -Uz compinit && compinit` を追加してください。

---

## 三、QCode.cc の設定

Codex CLI は QCode.cc サービスに接続するために2つの設定ファイルが必要です：

- `~/.codex/config.toml` — サーバーエンドポイントとモデル設定
- `~/.codex/auth.json` — API キー認証

### ステップ1：設定ディレクトリを作成

<div data-os="windows" markdown="1">

**Windows (PowerShell)：**

```powershell
mkdir $HOME\.codex
```

</div>

<div data-os="macos" markdown="1">

**macOS：**

```bash
mkdir -p ~/.codex
```

</div>

<div data-os="linux" markdown="1">

**Linux：**

```bash
mkdir -p ~/.codex
```

</div>

### ステップ2：config.toml を作成

`~/.codex/config.toml` に以下の内容を書き込みます：

```toml
model_provider = "crs"
model = "gpt-5.6-terra"
model_reasoning_effort = "high"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
```

**config.toml フィールドの詳細説明：**

| フィールド | 説明 |
|------|------|
| `model_provider` | 使用するモデルプロバイダー名。ここではカスタムの `crs` に設定 |
| `model` | デフォルトモデル。プログラミングなら `gpt-5.6-terra` 推奨 |
| `model_reasoning_effort` | 推論強度：`low`、`medium`、`high`。高いほど正確だが遅い |
| `disable_response_storage` | OpenAI による会話内容の保存を禁止（プライバシー保護） |
| `preferred_auth_method` | 認証方式、`apikey` に設定して API キーを使用 |
| `base_url` | QCode.cc アクセスポイントのアドレス（例では `api.qcode.cc` グローバル入口を使用。他のアクセスポイントは[エンドポイントと API パス](../getting-started/endpoints-and-api-paths)を参照）|
| `wire_api` | API プロトコルタイプ、Codex は `responses` を使用 |
| `requires_openai_auth` | OpenAI 形式の認証ヘッダーを付与する必要がある |
| `env_key` | 環境変数名、Codex はその変数から API キーを読み取る |

### ステップ3：auth.json を作成

`~/.codex/auth.json` に以下の内容を書き込みます：

```json
{
  "OPENAI_API_KEY": "cr_xxxxxxxxxx"
}
```

> `cr_xxxxxxxxxx` をあなたの [QCode.cc API キー](https://qcode.cc/dashboard) に置き換えてください。キーは `cr_` で始まります。

**auth.json の説明：**

- このファイルは Codex に API キーを提供し、`OPENAI_API_KEY` 環境変数を設定するのと同じ
- ファイル権限は `600`（本人だけが読み書き可能）に設定することを推奨：`chmod 600 ~/.codex/auth.json`
- `auth.json` と環境変数が同時に存在する場合、`auth.json` が優先

### ステップ4：環境変数を設定（オプションの代替案）

環境変数を通じてキーを提供する場合は（`auth.json` ではなく）、`CRS_OAI_KEY` を設定できます：

<div data-os="windows" markdown="1">

**Windows (PowerShell)：**

```powershell
# 一時設定（現在のセッション）
$env:CRS_OAI_KEY = "cr_xxxxxxxxxx"

# 永続設定（ユーザー環境変数に書き込み）
[System.Environment]::SetEnvironmentVariable("CRS_OAI_KEY", "cr_xxxxxxxxxx", [System.EnvironmentVariableTarget]::User)
```

</div>

<div data-os="macos" markdown="1">

**macOS：**

```bash
# 一時設定
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# 永続設定
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

<div data-os="linux" markdown="1">

**Linux：**

```bash
# 一時設定
export CRS_OAI_KEY="cr_xxxxxxxxxx"

# 永続設定（Bash）
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

# 永続設定（Zsh）
echo 'export CRS_OAI_KEY="cr_xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
```

</div>

環境変数を使用する場合、`auth.json` の `OPENAI_API_KEY` を `null` に設定します：

```json
{
  "OPENAI_API_KEY": null
}
```

### 利用可能なモデル

QCode.cc を通じて以下の Codex/GPT モデルを使用できます：

| モデル | 説明 | 推奨シナリオ |
|------|------|----------|
| **`gpt-5.5`** | 最新フラッグシップ、1M コンテキスト | 能力優先（推奨 ★） |
| **`gpt-5.4`** 🔥 | 最新世代の GPT、1M コンテキスト | 日常の複雑タスク（推奨） |
| `gpt-5.6-mini` | 軽量版、272K コンテキスト、高速 | 軽量／コストパフォーマンス |
| `gpt-5.6-terra` | GPT-5.6 フラッグシップ、コード最適化 | プログラミング／Codex CLI（推奨） |

> すべてのモデルは Claude Code と QCode.cc のプランのクォータを**共有**しています。モデルの切り替えに追加費用はかかりません。

---

## 四、基本情報使用チュートリアル

### 4.1 Codex を起動

ターミナルを開き、プロジェクトディレクトリに移動して、次を実行します：

```bash
cd /path/to/your/project
codex
```

Codex はターミナル対話インターフェース（TUI）を起動し、自然言語命令を入力できます。インターフェースは次の部分で構成されています：

- **トップステータスバー**：現在のモデル、承認モード、サンドボックス状態を表示
- **メインエリア**：AI の返信と操作ログ
- **ボトム入力ボックス**：命令を入力する場所

コマンドラインで直接タスクを提供することもできます（非対話モード）、スクリプト呼び出しに適しています：

```bash
# 対話型起動
codex

# 非対話モード：単一タスクを実行して終了
codex "このプロジェクト構造を読んで概要を提供してください"

# 画像を添付したタスク
codex -i screenshot.png "スクリーンショットに表示された UI 問題を修正"

# モデルを指定
codex -m gpt-5.4 "認証モジュールのエラー処理をリファクタリング"
```

### 4.2 最初のタスク：Codex に関数を書いてもらう

簡単な例から始めましょう。プロジェクトディレクトリで Codex を実行し、次を入力します：

```text
Python 関数を書いてください。文字列リストを受け取り、最も長い文字列を返します。複数ある場合は最初のものを返します。utils.py ファイルに保存してください。
```

Codex は次のステップを実行します：

1. **計画**：あなたの要件を分析し、実装方針を作成
2. **コード生成**：`utils.py` を作成し、関数を書き込む
3. **確認を求める**：デフォルトモードでは、Codex は行われるファイル変更を表示し、あなたが確認するのを待ちます

次のようなプロンプトが表示されます：

```text
Codex wants to create file: utils.py
─────────────────────────────────────
+ def find_longest(strings: list[str]) -> str:
+     """リスト中最長の文字列を返し、複数ある場合は最初のものを返します。"""
+     if not strings:
+         raise ValueError("リストは空にできません")
+     return max(strings, key=len)

Accept? [y/n]
```

`y` を入力して確認すると、Codex はコードをファイルに書き込みます。

次に、より多くの指示を与え続けることができます。Codex は同じセッション内でコンテキストを維持します：

```text
この関数にユニットテストを書いてください、pytest を使用
```

Codex は自動的に先ほど作成した `utils.py` を読み取り、対応するテストファイルを生成します。

### 4.3 Codex のサンドボックス実行モードを理解する

これは Codex の最も重要なセキュリティ機能の1つです。Codex は**サンドボックス**内でコマンドを実行し、3つのセキュリティレベルがあります：

| サンドボックスモード | ファイル読み取り | ファイル書き込み | コマンド実行 | ネットワークアクセス |
|----------|---------|---------|---------|---------|
| `read-only` | 許可 | 要確認 | 要確認 | 要確認 |
| `workspace-write`（デフォルト） | 許可 | ワークエリア内で許可 | ワークエリア内で許可 | デフォルトで禁止 |
| `danger-full-access` | 許可 | すべて許可 | すべて許可 | 許可 |

デフォルトの `workspace-write` モードは日常開発に最適です：Codex はプロジェクトディレクトリ内で自由にファイルの読み書きとコマンド実行ができますが、プロジェクト外のファイルやネットワークにはアクセスできません。

**タスクがネットワーク接続を必要とする場合**（例：`npm install`）、一時的にネットワークアクセスを有効にできます：

```bash
codex -c 'sandbox_workspace_write.network_access=true' "依存関係をインストールしてテストを実行"
```

### 4.4 Codex の変更をレビューして受け入れる

Codex のファイル変更は**承認ポリシー（Approval Policy）**に従います。デフォルトでは：

- **ファイル編集**：diff を表示して確認を待つ
- **シェルコマンド**：コマンド内容を表示して確認を待つ

Codex が変更を提出したとき、次のことができます：

- **受け入れる（y）**：変更を適用
- **拒否する（n）**：この変更をスキップ
- **詳細を表示**：diff をよく読んでから決定

> **ヒント**：`/diff` スラッシュコマンドを使用すると、いつでも現在のセッションですべての適用された変更を表示できます。

### 4.5 常用インタラクション技巧

**ファイル参照**：`@` の後にファイル名を入力すると、Codex は自動的にそのファイル内容を読み取ります：

```text
@src/app.py を確認してエラー処理を最適化してください
```

**シェルコマンドを実行**：`!` で始めると直接コマンドを実行でき、出力は Codex に渡されます：

```text
!cat error.log
上のエラーログを分析し、根本原因を見つけてください
```

**命令を追加**：Codex が実行中に `Enter` を押すと新しい命令を挿入でき、`Tab` を押すと次のラウンドの命令をキューに追加できます。

**履歴を編集**：`Esc` を2回押すと、入力ボックスが空のときに前のメッセージに戻って編集できます。続けて `Esc` を押すとより早いメッセージに戻り、`Enter` を押すとその地点から新しい会話の流れをフォークできます。

**パイプライン入力**：他のコマンドの出力をパイプラインで Codex に渡して分析できます：

```bash
# 最近の git 変更を分析
git diff HEAD~3 | codex "これらの変更をレビューし、潜在的な問題を見つけてください"

# エラーログを分析
cat /var/log/app/error.log | codex "これらのエラーの根本原因を分析"

# PR をレビュー
gh pr diff 42 | codex "この PR のコード品質とセキュリティをレビュー"
```

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

| ショートカット | 機能 |
|--------|------|
| `Tab` | ファイルパスの自動補完（`@` と組み合わせて使用） |
| `Enter` | Codex 実行中に新しい命令を挿入 |
| `Tab` | Codex 実行中に次のラウンドの命令をキューに追加 |
| `Esc` x 2 | 前のメッセージにロールバックして編集 |
| `Ctrl+C` | 現在の操作をキャンセル |

**スラッシュコマンド**：

| コマンド | 説明 |
|------|------|
| `/help` | ヘルプを表示 |
| `/mode` | 承認モードを切り替え |
| `/diff` | すべての変更を表示 |
| `/mcp` | 接続されている MCP サーバーを表示 |
| `/status` | 現在のセッション状態を表示 |
| `/compact` | トークンを節約するために会話履歴を圧縮 |
| `/permissions` | 権限設定を表示および変更 |
| `/review` | コードレビュー |

---

## 五、高度な設定

### 5.1 カスタム命令ファイル（AGENTS.md）

Codex は `AGENTS.md` ファイルをサポートして、AI にプロジェクトコンテキストと作業規範を提供します。Claude Code の `CLAUDE.md` と同様の役割を果たします。

**プロジェクトレベルの命令**：プロジェクトルートディレクトリに `AGENTS.md` を作成：

```markdown
# AGENTS.md

## プロジェクト説明
これは PostgreSQL データベースを使用した FastAPI バックエンドプロジェクトです。

## コード規範
- すべての関数には型注釈が必要
- 新しい API エンドポイントを追加する場合はテストも同時に作成
- コミット前に `make lint` を実行してコードスタイルを確認

## テストコマンド
- ユニットテスト：`pytest tests/unit/`
- インテグレーションテスト：`pytest tests/integration/`
- コードチェック：`make lint`
```

**グローバル命令**：`~/.codex/AGENTS.md` にグローバルデフォルトルールを作成すると、すべてのプロジェクトが継承します：

```markdown
# グローバル命令

- 常に日本語でコミュニケーションを取る
- コードコメントは英語を使用
- 関数型プログラミングスタイルを優先する
- 生成されたコードにはエラー処理が含まれている必要がある
```

**サブディレクトリオーバーライド**：特定のディレクトリに `AGENTS.override.md` を作成すると、上位ルールをオーバーライドできます：

```markdown
# services/payments/AGENTS.override.md

- このディレクトリ内のすべての変更は監査ログに書き込まれる必要がある
- 金額計算には Decimal 型を使用し、浮動小数点は使用しない
```

Codex は次の順序で命令ファイルを検索します：`AGENTS.override.md` > `AGENTS.md` > 設定されたフォールバックファイル。結合後の合計サイズの上限はデフォルトで 32KB、`project_doc_max_bytes` で調整できます。

### 5.2 承認モードの調整（Approval Mode）

Codex の3つの承認モードは異なる使用シナリオに適しています：

#### Suggest モード（最も安全）

**すべての操作に手動確認が必要**、ファイル編集とコマンド実行を含みます。学習段階または機密コードのレビューに適しています。

```bash
codex --approval-mode suggest
```

#### Auto-Edit モード（日常使用推奨）

**ファイル編集は自動実行、コマンド実行は確認が必要**。効率と安全の良好なバランス。

```bash
codex --approval-mode auto-edit
```

#### Full-Auto モード（完全自律）

**すべての操作が自動実行、確認不要**。分離環境（Docker コンテナ、CI/CD など）でのみ使用することを推奨。

> 🔴 **`--full-auto` は削除されました。** 代わりに `--sandbox workspace-write` を使います：

```bash
codex --sandbox workspace-write
```

> **セキュリティヒント**：`--sandbox workspace-write` はサンドボックス保護（ワークエリア内制限）を保持します。完全に無制限が必要な場合は `--dangerously-bypass-approvals-and-sandbox` を使用しますが、**非分離環境での使用は強くお勧めしません**。

**自動レビュー付き承認**（`--approve-for-me`、0.147.0 / 2026-08-07 追加）：Codex が実行前に低リスクの操作を自ら審査して承認します。「毎回確認」と「完全に開放」の中間です。

```bash
codex --approve-for-me
```

> ⚠️ Codex の flag は変化が速いです（`--full-auto` は削除された例）。本ページを含め、いかなる文書の flag 一覧も転記せず、**`codex --help` の実際の出力に従ってください**。

**config.toml でデフォルトモードを設定**：

```toml
# 個人開発推奨
approval_policy = "on-request"
sandbox_mode = "workspace-write"
```

**セッション中のモード切り替え**：`/mode` コマンドを使用すると再起動なしで切り替えられます：

```text
/mode suggest      # suggest モードに切り替え
/mode auto-edit    # auto-edit モードに切り替え
/mode full-auto    # full-auto モードに切り替え
```

#### 各シナリオの推奨設定

| シナリオ | 承認モード | サンドボックスモード |
|------|---------|---------|
| 個人日常開発 | `auto-edit` | `workspace-write` |
| チーム共有環境 | `suggest` | `workspace-write` |
| CI/CD パイプライン | `full-auto` | `workspace-write` |
| 学習と実験 | `suggest` | `workspace-write` |
| ワンスクリプトタスク | `full-auto` | `danger-full-access` |

### 5.3 MCP サーバーの設定

Codex は [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) をサポートし、外部ツールを接続して能力を拡張できます。

**コマンドラインで MCP サーバーを追加**：

```bash
codex mcp add my-server -- npx -y @some/mcp-server --config /path/to/config.json
```

**config.toml で設定**：

```toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "ghp_your_token" }
```

設定が完了したら Codex を再起動し、`/mcp` コマンドを使用して接続されているサーバーを確認します。MCP ツールは自動的に Codex の使用可能なツールリストに表示され、内蔵ツールと並んで表示されます。

**Codex 自体を MCP サーバーとして設定**：Codex は逆方向に実行されて MCP サーバーになることができ、他の AI Agent から呼び出せます。これはマルチエージェントシステムを構築する際に非常に便利です。

### 5.4 Profile の設定（マルチ環境管理）

プロジェクトごとに設定を変えたい場合（業務用と個人用など）は Profile を使います。**Codex 0.134.0 以降、`config.toml` 内に `[profiles.<名前>]` と書く旧方式は無効**になりました。現在は 1 プロファイル 1 ファイル、つまり `~/.codex/<名前>.config.toml` です。以下の 3 ブロックが新しい書き方の全体像です：

```toml
# ~/.codex/config.toml - default config (top-level keys only; no [profiles.x] tables)
model_provider = "crs"
model = "gpt-5.6-terra"

[model_providers.crs]
name = "crs"
base_url = "https://api.qcode.cc/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "CRS_OAI_KEY"
```

```toml
# ~/.codex/work.config.toml
model = "gpt-5.4"
model_reasoning_effort = "high"
```

```toml
# ~/.codex/personal.config.toml
model = "gpt-5.6-mini"
model_reasoning_effort = "medium"
```

起動時に指定します：

```bash
codex --profile work "認証モジュールをリファクタリング"
codex --profile personal "小さなスクリプトを書く"
```

✅ 以下の 3 点は**自社環境で実測**した挙動です（codex-cli 0.155.0、linux-x86_64、独立した HOME、モデルへのリクエストは送信せず）。よくある落とし穴はこのとおり：

- 旧テーブルを残したまま `--profile` を付けると**明示的にエラー**になります（黙って無視されるわけではありません）：

  ```text
  Error loading config.toml: --profile `work` cannot be used while ~/.codex/config.toml contains legacy `profile = "work"` or `[profiles.work]` config; move those settings into ~/.codex/work.config.toml and remove the legacy profile selector/table.
  ```

- 最上位の `profile = "work"` 指定子も同じく廃止済み：

  ```text
  Error: legacy `profile = "work"` config is no longer supported; use `--profile work` with `work.config.toml` instead
  ```
- **`--profile` を付けない場合、残った `[profiles.*]` テーブルは一切解決されません** —— `codex doctor` はそのまま `config.toml parse ok` と表示し、最上位の値が使われます。「エラーが出ない＝反映されている」ではないので、移行時に旧テーブルは削除してください。

なお `--profile` は実行系のサブコマンド（`codex`、`exec`、`review`、`resume`、`queue`、`archive`、`delete`、`unarchive`、`fork`、`mcp`、`sandbox`、`debug prompt-input`）でのみ有効です。`doctor` に付けると `--profile only applies to runtime commands ...` とエラーになります。Profile ファイルはユーザー設定より上位・プロジェクト設定とコマンドライン指定より下位の層です（5.6 参照）。

### 5.5 非対話モード（スクリプトと自動化）

Codex は対話型で使用するだけでなく、スクリプトや CI/CD パイプラインで非対話ツールとしても実行できます。prompt パラメータを直接渡すだけです：

```bash
# 基本用法：タスク実行後に終了
codex "README.md にインストール説明を追加"

# Full-Auto + 非対話：完全自律実行
codex --sandbox workspace-write "テストスイートを実行し、失敗したテストをすべて修正"

# transcript を出力ファイルに保存（監査用）
codex --sandbox workspace-write --transcript output.jsonl "エラー処理モジュールをリファクタリング"
```

**CI/CD で Codex を使用**：

```yaml
# GitHub Actions の例
- name: Auto-fix lint errors
  run: |
    npx @openai/codex --sandbox workspace-write "eslint --fix を実行してすべての lint エラーを修正し、修正をコミット"
  env:
    CRS_OAI_KEY: ${{ secrets.QCODE_API_KEY }}
```

**Codex SDK**：自分のプログラムから Codex を呼び出す必要がある場合は、公式 SDK を使用してプログラミング式で呼び出し、Codex を自分の開発ツールやワークフローに埋め込むことができます。

### 5.6 設定優先順位

複数の設定ソースが競合する場合、Codex は次の優先順位（高い方から低い方）で解決します：

1. **コマンドライン引数**（`--model`、`-c` など）
2. **プロジェクト設定**（`.codex/config.toml`、プロジェクトルートから現在のディレクトリまで、最も近いものが優先。信頼されたディレクトリでのみ読み込まれ、プロジェクト層の `model_provider`、`model_providers`、`profile`、`profiles` といったキーは Codex に無視されます）
3. **Profile ファイル**（`--profile <name>` で選ぶ `~/.codex/<name>.config.toml`）
4. **ユーザー設定**（`~/.codex/config.toml`）
5. **システム設定**（`/etc/codex/config.toml`、Unix システム）
6. **内置デフォルト値**

この優先順位を理解することで、異なるレベルで正確に動作を制御できます。例えば、`~/.codex/config.toml` で共通デフォルト値を設定し、プロジェクトの `.codex/config.toml` で特定設定をオーバーライドし、コマンドライン引数でワンショットの調整を行います。

---

## 六、Claude Code と Codex の比較

一言でいうと：**Claude Code は対話型のペアプログラミング、Codex は自律的なタスク実行**です。Claude Code は探索的なデバッグ、複雑なリファクタリング、アーキテクチャの把握に向き、Codex は要件が明確な機能開発、一括移行、CI/CD の自動化に向きます。指示ファイルはそれぞれ `CLAUDE.md` と `AGENTS.md`、どちらも MCP に完全対応し、**同じ QCode.cc プラン枠を共有**するため切り替えコストはゼロです。

実行モデル・コンテキスト長・サンドボックス・マルチエージェント・OSS かどうかなど 13 項目の詳細比較 → [Codex vs Claude Code 比較](/docs/getting-started/codex-vs-claude-code)。

---

## 七、実践例

以下の実際のシナリオを通じて Codex の使用方法をデモします。各例は具体的なコマンドと期待される効果を含みます。

### 例1：新しいプロジェクトを理解する

見覚えのないコードベースを引き継いだとき：

```bash
cd /path/to/new/project
codex
```

対話インターフェースで：

```text
このプロジェクトは何をしますか？ディレクトリ構造、主要モジュール、技術スタックを分析し、簡潔なアーキテクチャ図（ASCII art を使用）を提供してください。
```

Codex はプロジェクト内のファイルをスキャンし、`package.json`、`requirements.txt`、`go.mod` などの依存関係ファイルを分析し、キーエントリファイルを読み取り、包括的なプロジェクト概要を提供します。

### 例2：コードレビュー

```bash
codex "src/ ディレクトリで最後の git commit のすべての変更をレビューしてください。重点的に確認する内容：
1. 潜在的なバグ（null ポインタ、境界条件）
2. セキュリティリスク（SQL インジェクション、XSS、ハードコードされたキー）
3. パフォーマンス問題（N+1 クエリ、不必要なループ）
具体的なコード位置と修正提案を提供してください。"
```

### 例3：一括リファクタリング

```bash
codex --sandbox workspace-write "プロジェクト内のすべての Python ファイルの print() 呼び出しを logging モジュールに置き換えてください。
具体的な要件：
1. 各ファイルの上部に import logging を追加
2. logger = logging.getLogger(__name__) を作成
3. print() を logger.info() に置き換える
4. 元のフォーマット文字列を維持
5. 置き換え完了後に pytest を実行して何も壊れていないことを確認"
```

Codex はファイルを1つずつ処理し、コードの一貫性を維持し、最後にテストを実行して検証します。

### 例4：完全なテストスイートを作成

```bash
codex "src/services/user_service.py の完全なユニットテストを作成してください。要件：
1. pytest + pytest-mock を使用
2. すべてのパブリックメソッドをカバー
3. 正常パスと異常パステストを含める
4. 外部依存をモック（データベース、HTTP リクエスト）
5. テストファイルを tests/unit/test_user_service.py に保存
6. テストを実行してすべて合格することを確認"
```

### 例5：自律的にテストを修正

Full-Auto モードの古典的な用例 — Codex に失敗したテストを自律的に修正させます：

```bash
codex --sandbox workspace-write "すべてのテストを実行してください。失敗したものがある場合：
1. 失敗の原因を分析
2. コードを修正（テストではなくコードを修正）
3. テストを再実行
4. すべてのテストが合格するまで上記のステップを繰り返す
最後に修正サマリーを提供してください。"
```

### 例6：設計稿から UI を実装

```bash
codex -i design.png "この設計稿に基づいて、React + Tailwind CSS でこのページを実装してください。
要件：
1. レスポンシブレイアウト（モバイルサポート）
2. 設計稿のピクセルパーフェクト再現
3. コンポーネント分割が適切
4. 基本的なインタラクション状態を追加（hover、focus）"
```

### 例7：データベースマイグレーション

```bash
codex "users テーブルに avatar_url フィールドを追加する必要があります（varchar 500, nullable）。
してください：
1. Alembic マイグレーションスクリプトを作成
2. SQLAlchemy モデルを更新
3. 関連する Pydantic schema を更新
4. CRUD 操作関数を更新
5. 対応する API エンドポイントを追加（GET/PUT）
6. マイグレーションを実行して成功を確認"
```

### 例8：CI/CD で Changelog を自動生成

```bash
codex --sandbox workspace-write "前回の release tag から現在までのすべての git commit を分析し、
conventional commits 規範に従って分類し、
CHANGELOG.md の更新内容を生成してください。
含める内容：新機能、バグ修正、破壊的変更、その他の改善。"
```

---

## 八、よくある質問

### 設定ファイルが見つからない

**問題**：Codex が設定ファイル找不到または設定を読み込めない

**解決**：

1. 設定ディレクトリが存在するか確認：`ls ~/.codex/`
2. `config.toml` と `auth.json` の両方のファイルが存在することを確認
3. `config.toml` の TOML 構文が正しいか確認（一般的なエラー：引用符が不足、スペルミス）
4. `codex --config-dump` を使用して実際に読み込まれている設定を表示

### API キー認証失敗

**問題**：`401 Unauthorized` または API Key が無効と表示される

**解決**：

1. API キーの形式が正しいことを確認（`cr_` で始まる）
2. `auth.json` 内のキーが完全であるか確認（余分なスペースや改行がない）
3. 環境変数を使用する場合は、変数名が `CRS_OAI_KEY` であることを確認（`config.toml` の `env_key` と同じ）
4. [QCode.cc コンソール](https://qcode.cc/dashboard) にログインして、キーの状態と残りのクォータを確認

### ネットワーク接続問題

**問題**：QCode.cc サービスに接続できない、タイムアウトまたは接続拒否

**解決**：

1. ネットワークが正常か確認：`curl -I https://api.qcode.cc`
2. `base_url` 設定が正しいか確認（`https://api.qcode.cc/openai` である必要がある）
3. 代替ノードを試す：
   - 深センノード：`https://api.qcode.cc/openai`
4.  会社のプロキシ/VPN を使用する場合は、HTTPS リクエストがブロックされないようにプロキシ設定を確認

### モデル選択の提案

**問題**：どのモデルを選択すればよいかわからない

**提案**：

| あなたのニーズ | 推奨モデル | 理由 |
|---------|---------|------|
| プログラミング | `gpt-5.6-terra` | コード最適化 |
| 複雑タスク | `gpt-5.4` | 汎用能力、1M コンテキスト |
| 軽量タスク | `gpt-5.6-mini` | クォータ消費が少ない |
| 最強の能力 | `gpt-5.5` | 最新フラッグシップ |

`config.toml` でデフォルトモデルを設定した後、一時的に切り替えることもできます：

```bash
codex -m gpt-5.4 "この複雑な並行バグを分析"
```

### サンドボックス制限によるコマンド失敗

**問題**：Codex が実行しようとしたコマンドがサンドボックスに拒否された

**解決**：

1. ネットワーク接続操作（例：`npm install`）の場合、一時的にネットワークを有効にする：
   ```bash
   codex -c 'sandbox_workspace_write.network_access=true' "依存関係をインストール"
   ```
2. プロジェクトディレクトリ外のファイルに書き込む必要がある場合、一時的に書き込み範囲を拡張できます：
   ```bash
   codex --sandbox danger-full-access "出力を /tmp/result.txt に保存"
   ```
3. セッション内で `/permissions` を使用して現在の権限を表示および調整

### 費用の説明

**問題**：Codex と Claude Code の費用はどのように計算されますか？

**説明**：

- Codex と Claude Code は**QCode.cc のプランのクォータを共有**
- 同じプランは両方のツールで同時に使用可能
- 費用は実際のトークン消費に基づいて計算され、ツールごとに区別されない
- Full-Auto モードでは Codex は自律的に複数ラウンド反復するため、単一タスクのトークン消費は高くなる可能性がありますが、開発者のインタラクション時間が節約されます
- `/cost` コマンドを使用して現在のセッションのトークン使用量を表示するか、[QCode.cc コンソール](https://qcode.cc/dashboard) で全体のクォータ使用状況を確認することを推奨

### AGENTS.md と CLAUDE.md は共存できますか？

**できます**。プロジェクトが Codex と Claude Code の両方で使用される場合：

- Codex は `AGENTS.md` のみを読み取り、`CLAUDE.md` を無視
- Claude Code は `CLAUDE.md` のみを読み取り、`AGENTS.md` を無視します
- 両者は互いに干渉せず、ツールごとに個別の指示ファイルを維持できます
- 両ファイルの中核となる規範（テストコマンド、コードスタイルなど）は一致させることを推奨します

---

## 十、関連ドキュメント

- [環境変数の設定](/docs/getting-started/environment) — Claude Code の環境変数設定
- [クイックスタート](/docs/getting-started/quick-start) — Claude Code 入門
- [Aider 連携](/docs/ide/aider) — もう一つのオープンソース AI コーディングアシスタントの設定
- [CLI テクニック](/docs/usage/cli-tips) — Claude Code のコマンドライン応用テクニック