Codex には、ツール、ワークフロースキル、フックを備えた公式の Chorus 統合があります。
サポートされる Chorus デーモンのバックエンドでもあります。

インストール前に、[エージェントのアクセスを準備する](/ja/guides/administrator-setup/)に従って
API キーを作成します。

## 統合をインストールする

まだ Codex を導入していない場合はインストールします。

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

次に、`chorus` CLI で Chorus 統合をインストールします。

```bash
npm install --global @chorus-aidlc/chorus
chorus agents add --agents codex
```

プロンプトが出たら、Chorus URL と API キーを入力します。`chorus agents add` は Codex
プラグインをインストールし、`CHORUS_URL`、`CHORUS_API_KEY`、`CHORUS_AGENT_PROFILE` を
`~/.codex/.env` に書き込み、`~/.codex/config.toml` に `bearer_token_env_var = "CHORUS_API_KEY"`
を設定します。これにより Codex は環境変数からキーを読み、設定ファイルにキーが書き込まれることは
ありません。

### 既存の App Server に設定を適用する

Chorus 0.21.1 以降では、認証情報と MCP 設定の保存に成功すると、対話型設定で実行中の **Codex App Server** を保存済み環境で再起動するか確認できます。Chorus デーモンとは別です。Codex の全パスは `CODEX_HOME`（既定は `~/.codex`）に従います。

- 再起動は他の Codex セッションや作業を中断する可能性があります。既定は**いいえ**で、明示的な `y` または `yes` だけが再起動を許可します。
- 非対話型、`--yes`、`CHORUS_DAEMON_HEADLESS=1` では延期します。一般の `--yes` はセッション中断の許可ではありません。
- App Server が停止中なら起動しません。コマンド非対応、状態不明、設定失敗、または身元の上書きを拒否した場合も延期します。プラグインのみの更新ではこの手順を省略します。
- 再起動に失敗しても保存した設定は残ります。成功はコマンドの完了だけを示し、新たな認証情報、MCP ツール、モデル呼び出しの検証ではありません。

延期した場合は影響するセッションの作業を保存し、安全なときに対話型端末で `chorus agents add --agents codex` を `--yes` なしで再実行します。対応する実行中サーバーには専用の確認が再表示され、保存済み環境を使います。端末 UI を開き直すだけでは旧サーバーに再接続することがあります。その後、下記の接続確認を行ってください。再起動機能のために Codex 自体を自動更新することはありません。

## リモート起動を有効にする

対話的な Codex セッションからのみ Chorus を使う場合は、このセクションを飛ばしてください。
それ以外の場合は、[エージェントランタイムを接続する](/ja/guides/operator-onboarding/)に従い、バックエンドとして
`codex` を選びます。[Chorus デーモンを運用する](/ja/guides/daemon-operations/)に従ってオンラインを維持する前に、
フォアグラウンドで接続を確認してください。

## 0.20.0 のデーモン動作

各デーモン起動は、独立した `codex app-server --listen stdio://` プロセスで 1 ターンを実行します。検証済みの最小基準は **codex-cli 0.157.1** です。それ以前は未検証で、必要なプロトコルに対応していなければ起動に失敗します。`codex exec` へのフォールバックや切り替えはありません。独自の `CODEX_HOME` を使う場合は、そこにも Chorus 統合をインストールしてください。Chorus プラグインの更新では Codex CLI 自体は更新されません。

### モデル設定とセッションの継続

デーモンの `args` は、モデル指定（`--model` / `-m`）と、`model_reasoning_effort` など許可された `-c` / `--config` 設定に対応します。それ以外のオプション（`--oss`、画像入力、未知のスイッチなど）は起動前にエラーになります。通信、作業ディレクトリ、権限、管理対象 MCP の制御は保護されています。対応する設定か [CLI](/ja/reference/cli/) の明示的なフォアグラウンドコマンドを使ってください。`chorus agents run --type codex -- exec ...` や `... -- resume ...` の動作は従来どおりです。

デーモンは、以前の `exec` バックエンドが作ったスレッドも含め、保存済みのスレッドを現在の作業ディレクトリと権限設定で再開します。

- **代替スレッド**：明確な「no rollout found」の応答があった場合に限り、一度だけ代替スレッドを作り、会話に継続性の通知を表示します。それ以外の再開エラーでは起動を停止し、Chorus セッションと Codex スレッドの保存済みの対応付けを保持します。
- **保存済みのセッション記録**：記録を読み取れない場合は警告を出して新規に開始し、保存できない場合は今後の継続性が損なわれる可能性があると警告します。
- **新しいメッセージ**は後続のターンを待ち、実行中のターンの方向は変えません。
- **トークン使用量**は現在のターンの分だけを報告します。再開したスレッドに信頼できる開始時の値がない場合は、スレッドの履歴を計上せず、そのターンの使用量を省略します。

### 制限モードとツール承認

`--chorus-only` は読み取り専用で、対話的な承認とそのターンのネットワークアクセスを無効にします。ネイティブの承認・ユーザー入力要求は拒否し、安全に拒否できない要求は起動を失敗させます。質問は Chorus のコメントか要件詳細化を使ってください。検証済みの Codex では、承認を必要とする Chorus MCP ツール（`chorus_checkin` を含む）も拒否される場合があります。ターン完了は MCP 呼び出しの成功を保証しません。

チェックインを許可すると決めた場合は、`~/.codex/config.toml`（またはそのエージェントの `CODEX_HOME/config.toml`）に次を明示します。

```toml
[mcp_servers.chorus.tools.chorus_checkin]
approval_mode = "approve"
```

この設定は 0.157.1 の新規・再開スレッドで、読み取り専用かつ対話的承認が無効のまま動作することを検証済みです。許可するのはチェックインだけです。コメントや課題の更新には個別の明示的な許可と検証が必要です。デーモンの `args` ではなく Codex の設定に記載してください。デーモンが代わりに承認することはありません。

### 中断とトラブルシューティング

許可された中断は `turn/interrupt` を送信し、起動中のキャンセルは通信を閉じます。その後、デーモンが時間制限付きでプロセスツリーを後始末します。Windows には Windows PowerShell（`Get-CimInstance`）と `taskkill` が必要です。

起動・プロトコルエラーでは `codex --version`、ログイン、モデル設定、ローカルセッション保存先の権限を確認してください。初期化は 30 秒、起動時 RPC 応答は 60 秒、終了処理は 10 秒が上限です。実行中のターンには無通信時間や総実行時間の上限はなく、停止した場合は **中断** を使います。`CLOSED` は情報メッセージです。プロセスの終了コードがゼロでも、失敗・中断・終端イベント欠落を成功とは扱いません。[セッションを中断して再開する](/ja/guides/session-recovery/)も参照してください。

## 接続を確認する

Codex を開き、`check in to chorus` を依頼します。応答が想定したエージェントの身元と権限を示す
ことを確認します。`/plugins` と `/hooks` を使って、Chorus プラグインとフックが有効になっている
ことも確認できます。

デーモンモードでは、Chorus の**設定 → エージェント**を開き、想定したホストと作業ディレクトリが
オンラインであることを確認します。

## 機能と制限

- 統合は Chorus MCP ツール、ワークフロースキル、そして Codex フックを提供します。
- デーモンモードは、リモート起動、追加指示、中断、再開をサポートします。
- Codex にはサブエージェント起動前のフックがないため、Chorus のワークフロースキルがサブエージェントのセッションを
  明示的に管理します。
- リモート作業はローカルユーザーのアクセス権を継承します。信頼できる作業ディレクトリのみを
  登録してください。

共通の運用手順については、[リモートのエージェントで作業を始める](/ja/guides/remote-control/)と
[セッションを中断して再開する](/ja/guides/session-recovery/)を参照してください。

## ターミナルから再開する

自分のターミナルから進行中の会話を引き継ぐには、チャット UI からそのセッション ID をコピーし
（トランスクリプトのヘッダーにある **セッション ID をコピー**）、その会話の作業ディレクトリで実行します。

```bash
codex exec resume <thread_id>
```

Codex は独自のスレッド ID を生成するため、コピーした値はそのスレッド ID であり、Chorus が提供する
セッション ID ではありません。Chorus が実行を再開するときに Codex に渡すのも、まさにこの値です。完全な流れは
[セッションを中断して再開する](/ja/guides/session-recovery/#ターミナルから引き継ぐ)を参照してください。

## よくある問題

- **`codex` が見つからない：** `@openai/codex` をグローバルにインストールし、`chorus agents add`
  を再実行します。
- **設定後も旧認証情報を使う、または `CHORUS_API_KEY` がない**：実際の `CODEX_HOME` の `.env` を確認し、`chorus agents add --agents codex` と上記の安全な再起動を行います。キーの交換は無効または失効した場合のみ必要です。
- **プラグインまたはフックが無効：** `/plugins` と `/hooks` で有効にし、Codex を再起動します。
- **デーモンがオフライン：** `chorus daemon status` を実行し、次に
  [エージェント接続のトラブルシューティング](/ja/guides/troubleshooting/)を参照します。