# Codex クイックスタート

> ⚡ **おすすめ：ワンクリック設定** — `curl -fsSL https://qcode.cc/install/codex.sh | bash`（Windows は `irm https://qcode.cc/install/codex.ps1 | iex`）で CLI のインストール、`~/.codex` 設定の書き込み、疎通確認までまとめて行えます。[ワンクリック設定スクリプト](/docs/getting-started/one-click-install) を参照してください。手動設定を行う場合は、このまま読み進めてください。

すでに Claude Code を使っているなら、このガイドで **5 分** あれば Codex CLI を動かせます。どちらのツールも QCode.cc のプラン枠を共有し、同じ API キーを使うため、設定さえ済めば自由に行き来できます。

QCode.cc のアカウントがまだない場合は、先に [登録してプランを選んで](https://qcode.cc/pricing) ください。

---

## 前提条件

始める前に、環境が次の条件を満たしているか確認してください：

| 要件 | バージョン | 確認方法 |
|-------------|---------|-------------|
| Node.js | v22 以降 | `node --version` |
| npm | v10 以降 | `npm --version` |
| Git | 任意 | `git --version` |
| OS | macOS / Linux / Windows (WSL) | - |
| QCode.cc キー | `cr_` で始まる API キー | [ダッシュボード](https://qcode.cc/dashboard) |

> **補足**：Codex のカーネルレベルサンドボックスは Linux で最も力を発揮します。macOS と Windows WSL も完全にサポートされていますが、一部のサンドボックス機能に制限が出ることがあります。

---

## ステップ 1：Codex CLI のインストール

次のいずれかの方法を選んでください：

### オプション A：npm でグローバルインストール（推奨）

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

# 中国のユーザーは淘宝ミラーで高速化できます
npm install -g @openai/codex --registry=https://registry.npmmirror.com
```

### オプション B：Homebrew（macOS）

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

### オプション C：ソースからビルド

```bash
git clone https://github.com/openai/codex.git
cd codex
cargo build --release
cp target/release/codex ~/.local/bin/
```

インストールを確認します：

```bash
codex --version
# バージョンが表示されます（ウェブ上の古い数字ではなく、この環境の `codex --version` を信頼してください）
```

---

## ステップ 2：QCode.cc の設定

### 2.1 設定ディレクトリを作る

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

### 2.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"
```

設定項目の意味：

| 項目 | 説明 |
|-------|------|
| `model_provider` | カスタムプロバイダー `crs` を使う |
| `model` | 既定のモデル。`gpt-5.6-terra` を推奨。後述の「利用可能なモデル」を参照 |
| `model_reasoning_effort` | 推論の深さ。`low` / `medium` / `high` |
| `base_url` | QCode.cc のアジア太平洋エンドポイント |
| `wire_api` | API プロトコル。`responses` を指定 |
| `env_key` | API キーを入れる環境変数の名前 |

### 2.3 auth.json を作る

`~/.codex/auth.json` を作成します：

```json
{
  "OPENAI_API_KEY": "cr_your_key_here"
}
```

> `cr_your_key_here` は [QCode.cc ダッシュボード](https://qcode.cc/dashboard) の API キーに置き換えてください。

### 2.4 環境変数を設定する

`auth.json` の代わりにこちらでも構いません（どちらか一方で十分です）：

```bash
# 一時的（現在のターミナルのみ）
export CRS_OAI_KEY="cr_your_key_here"

# 永続的（Bash の場合）
echo 'export CRS_OAI_KEY="cr_your_key_here"' >> ~/.bashrc
source ~/.bashrc

# 永続的（Zsh の場合）
echo 'export CRS_OAI_KEY="cr_your_key_here"' >> ~/.zshrc
source ~/.zshrc
```

> **ヒント**：これは Claude Code で使うキーと同じものです。すでに Claude Code を使っているなら、[ダッシュボード](https://qcode.cc/dashboard) の同じ場所にあります。

---

## ステップ 3：設定の確認

簡単なタスクで接続をテストします：

```bash
codex "print hello world"
```

Codex が正常に起動して応答が返ってくれば、設定は成功です。

### チェックリスト

- Codex がエラーなく起動する
- API リクエストが QCode.cc 経由で通る（ネットワークのタイムアウトが出ない）
- モデルの応答が正しい（指示を理解している）

うまくいかない場合は [よくある質問](#faq) を参照してください。

---

## ステップ 4：最初の実践タスク

実際の場面で Codex の力を試してみましょう。プロジェクトのディレクトリに移動します：

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

### 例 1：プロジェクト構造を分析する

```bash
codex "このプロジェクトのディレクトリ構成と技術スタックを分析して、簡潔に概要をまとめて"
```

### 例 2：コードを生成する

```bash
codex "utils/date-formatter.ts を作成して、次の機能を実装して：
  1. 日付を YYYY-MM-DD 形式に整形する
  2. 2 つの日付の間の日数を計算する
  3. ある日付が営業日かどうかを判定する
  4. 各関数に完全な JSDoc コメントと単体テストを付ける"
```

### 例 3：一括で修正する

```bash
codex "src/ 配下のすべての .js ファイルを .ts に変換し、型注釈を追加して"
```

Codex はサンドボックス内で自律的にタスクを完了し、最後に変更サマリーを提示します。

---

## 3 つの権限モード

Codex には自動化の度合いを制御する 3 つの権限モードがあります：

### suggest（提案モード）

```bash
codex --suggest "auth モジュールをリファクタリングして"
```

- 分析と提案のみ。**ファイルは一切変更しない**
- 提案された変更は自分で適用する
- 向いている場面：コードの学習、方針の検討

### auto-edit（自動編集モード）

```bash
codex --auto-edit "エラーハンドリングを追加して"
```

- **ファイルは自動で編集する**が、コマンド実行の前には確認を求める
- 向いている場面：日常の開発（既定としておすすめ）

### 完全自動（`--sandbox workspace-write`）

```bash
codex --sandbox workspace-write "テストを実行して、失敗をすべて修正して"
```

- ファイル編集とコマンド実行を自動で行い、**確認を求めない**
- すべての操作はサンドボックス内で行われ、システムには影響しない
- 向いている場面：CI/CD への組み込み、一括タスク

> 既定のモードは `config.toml` にも書けます：`approval_mode = "auto-edit"`

---

## よく使うコマンド

| コマンド | 説明 |
|---------|------|
| `codex "指示"` | タスクを渡して Codex を起動する |
| `codex --model gpt-5.4` | モデルを指定する |
| `codex --sandbox workspace-write "指示"` | 完全自動モード |
| `codex --suggest "指示"` | 提案のみ、実行しない |
| `codex --auto-edit "指示"` | 自動編集。コマンドは確認あり |
| `codex --version` | バージョンを表示 |
| `codex --help` | ヘルプを表示 |

### 利用可能なモデル

QCode.cc 経由で次のモデルが使えます：

| モデル | 説明 | おすすめ用途 |
|-------|------|-----------------|
| `gpt-5.6-terra` | GPT-5.6 のフラッグシップ | コーディング / 複雑なタスク（おすすめ ★） |
| `gpt-5.6-sol` / `gpt-5.6-luna` | GPT-5.6 フラッグシップ系 | ハイエンドな性能 |
| `gpt-5.5` | 前世代フラッグシップ、1M コンテキスト | 日常の複雑なタスク |
| `gpt-5.4` | 安定版、1M コンテキスト | 日常のタスク / コスト重視 |
| `gpt-5.6-mini` / `gpt-5.6-nano` | 軽量・高速 | 軽いタスク |

---

## プロジェクト設定：AGENTS.md

プロジェクトのルートに `AGENTS.md` を置くと、そのプロジェクトでの Codex の振る舞いを定義できます。Claude Code の `CLAUDE.md` に相当します：

```markdown
# AGENTS.md

- TypeScript の strict モードを使う
- コードスタイルは ESLint + Prettier に従う
- テストフレームワーク：Vitest
- コミット前に `npm run lint && npm test` を実行する
- コンポーネントのファイル名は PascalCase
```

> 詳しい設定は [AGENTS.md 設定ガイド](/docs/usage/agents-md) を参照してください。

---

## Claude Code との併用

2 つのツールは QCode.cc の枠を共有するため、併用するのがベストプラクティスです：

```bash
# ターミナル 1：Claude Code で問題を分析する
$ claude
> パフォーマンスのボトルネックはどこ？方針を一緒に考えて。

# ターミナル 2：Codex で一括実行する
$ codex "この方針に沿って src/api/ 配下のすべてのデータベースクエリを最適化して：
  1. クエリキャッシュを追加
  2. N+1 クエリを解消
  3. インデックスの提案コメントを追加"
```

> 併用パターンをもっと見るには [Codex vs Claude Code 比較](/docs/getting-started/codex-vs-claude-code) を参照してください。

---

## 次のステップ

設定は完了です。Codex を使い始められます。次の記事もおすすめです：

- [AGENTS.md 設定ガイド](/docs/usage/agents-md) -- Codex のプロジェクト挙動をカスタマイズする
- [Codex vs Claude Code 比較](/docs/getting-started/codex-vs-claude-code) -- 違いと併用の仕方を理解する
- [Codex 統合設定](/docs/ide/codex) -- 完全な設定リファレンス（Windows と複数 OS の詳細手順を含む）
- [CLI の便利な使い方](/docs/usage/cli-tips) -- AI コーディングの効率化テクニック

---

## よくある質問

### Q: インストールが `npm ERR! EACCES` で失敗する

**原因**：npm のグローバルインストール先への権限が足りていません。

**対処**：

```bash
# 方法 A：sudo を使う（恒久的な運用としては非推奨）
sudo npm install -g @openai/codex

# 方法 B：npm をユーザーディレクトリ配下に設定する（推奨）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex
```

### Q: `API key not found` や認証エラーが出る

**確認手順**：

1. `~/.codex/auth.json` のキーが `cr_` で始まっているか
2. 環境変数 `CRS_OAI_KEY` が設定されているか：`echo $CRS_OAI_KEY`
3. キーが失効していないか：[QCode.cc ダッシュボード](https://qcode.cc/dashboard) で確認
4. `config.toml` の `env_key` のつづりが正しいか

### Q: 接続がタイムアウトする、ネットワークエラーになる

**確認手順**：

1. `base_url` が `https://api.qcode.cc/openai` になっているか
2. ネットワークの疎通を確認：`curl -I https://api.qcode.cc`
3. 主エンドポイントが使えない場合は代替を試す：
   - バックアップ：`https://asia.qcode.cc/openai`

### Q: Codex のキーは Claude Code と同じ？

**同じです**。どちらも同じ QCode.cc の API キーを使い、枠も共有します。別途キーを用意する必要はありません。

### Q: Windows でも動く？

**動きます**。ただし WSL（Windows Subsystem for Linux）の利用を推奨します。ネイティブ Windows のサポートも改善が進んでいます。Windows の詳細な手順は [Codex 統合設定](/docs/ide/codex) を参照してください。