Codex에는 도구, 워크플로 스킬, 훅을 갖춘 공식 Chorus 통합이 있습니다. 지원되는 Chorus 데몬
백엔드이기도 합니다.

설치 전에 [에이전트 액세스 준비](/ko/guides/administrator-setup/)에 따라 에이전트 키를
만드세요.

## 통합 설치

아직 Codex가 없다면 설치합니다.

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

그런 다음 `chorus` CLI로 Chorus 통합을 설치합니다.

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

프롬프트가 나오면 Chorus URL과 에이전트 키를 입력합니다. `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를 사용한다면 이 섹션을 건너뛰세요. 그렇지 않다면
[에이전트 런타임 연결](/ko/guides/operator-onboarding/)에 따라 백엔드로 `codex`를 선택합니다.
[Chorus 데몬 운영](/ko/guides/daemon-operations/)으로 온라인 상태를 유지하기 전에, 포그라운드에서
연결을 확인하세요.

## 0.20.0의 데몬 동작

데몬은 깨울 때마다 독립된 `codex app-server --listen stdio://` 프로세스로 한 턴을 실행합니다. 검증된 최소 기준은 **codex-cli 0.157.1**입니다. 이전 버전은 검증되지 않았으며, 필요한 프로토콜을 지원하지 않으면 깨우기가 실패합니다. `codex exec`로 돌아가는 대체 경로나 백엔드 전환 옵션은 없습니다. 사용자 지정 `CODEX_HOME`을 쓴다면 그곳에도 Chorus 통합을 설치하세요. Chorus 플러그인을 업데이트해도 Codex CLI 자체는 업그레이드되지 않습니다.

### 모델 옵션과 세션 연속성

데몬 `args`는 모델 선택(`--model` / `-m`)과 `model_reasoning_effort` 같은 허용된 `-c` / `--config` 설정을 지원합니다. 그 밖의 옵션(`--oss`, 이미지 입력, 알 수 없는 스위치 포함)은 실행 전에 오류가 발생합니다. 전송, 작업 디렉터리, 권한, 관리형 MCP 제어는 보호되어 재정의할 수 없습니다. 지원되는 구성 설정을 쓰거나, [CLI](/ko/reference/cli/)로 명시적인 포그라운드 명령을 실행하세요. `chorus agents run --type codex -- exec ...` 및 `... -- resume ...`의 기존 동작은 유지됩니다.

데몬은 저장된 스레드를 현재 작업 디렉터리와 권한 정책으로 재개하며, 이전 `exec` 백엔드가 만든 스레드도 포함됩니다.

- **대체 스레드**: 명확한 “no rollout found” 응답일 때만 대체 스레드를 한 번 만들고, 대화에 연속성 알림을 표시합니다. 다른 재개 오류가 나면 깨우기를 중단하고, Chorus 세션과 Codex 스레드 사이의 저장된 연결을 유지합니다.
- **저장된 세션 기록**: 데몬이 저장된 세션 기록을 읽지 못하면 경고와 함께 새로 시작하고, 저장하지 못하면 이후 연속성이 떨어질 수 있다고 경고합니다.
- **새 메시지**는 다음 턴을 기다리며, 실행 중인 턴의 방향을 바꾸지 않습니다.
- **토큰 사용량**은 현재 턴의 것만 보고합니다. 재개한 스레드에 신뢰할 수 있는 시작 값이 없으면, 스레드의 과거 사용량을 세는 대신 해당 턴의 사용량을 생략합니다.

### 제한 모드와 도구 승인

`--chorus-only`는 Codex를 읽기 전용으로 유지하며, 해당 턴 동안 대화형 승인과 네트워크 접근을 비활성화합니다. 네이티브 승인이나 사용자 입력 요청은 거부되며, 안전하게 거부할 수 없는 요청은 깨우기를 실패시킵니다. 질문은 Chorus 댓글이나 요구사항 구체화로 해야 합니다. 검증된 Codex 버전에서는 `chorus_checkin`을 포함해 승인이 필요한 Chorus MCP 도구도 거부될 수 있습니다. 턴이 완료되었다고 해서 그 턴의 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`는 정보 표시일 뿐입니다. 실패했거나 중단되었거나 결과를 보고하지 않은 턴은 프로세스가 코드 0으로 종료되더라도 성공이 아닙니다. 복구 절차는 [세션 중단과 재개](/ko/guides/session-recovery/)를 참고하세요.

## 연결 확인

Codex를 열고 `check in to chorus`를 요청합니다. 응답이 예상한 에이전트 신원과 권한을 보여
주는지 확인합니다. `/plugins`와 `/hooks`를 사용해 Chorus 플러그인과 훅이 활성화되어 있는지도
확인할 수 있습니다.

데몬 모드에서는 Chorus의 **설정 → 에이전트**를 열고 예상한 호스트와 작업 디렉터리가 온라인인지
확인합니다.

## 기능과 제한

- 통합은 Chorus MCP 도구, 워크플로 스킬, 그리고 Codex 훅을 제공합니다.
- 데몬 모드는 원격 시작, 후속 지시, 중단, 재개를 지원합니다.
- Codex에는 서브에이전트 생성 전(pre-spawn) 훅이 없으므로, Chorus 워크플로 스킬이 서브에이전트 세션을 명시적으로
  관리합니다.
- 원격 작업은 로컬 사용자의 접근 권한을 상속합니다. 신뢰하는 작업 디렉터리만 등록하세요.

공통 운영 절차는 [원격 에이전트에서 작업 시작](/ko/guides/remote-control/)과
[세션 중단과 재개](/ko/guides/session-recovery/)를 사용하세요.

## 터미널에서 재개하기

자신의 터미널에서 진행 중인 대화를 넘겨받으려면, 채팅 UI에서 해당 세션 ID를 복사한 뒤
(대화 기록 헤더의 **세션 ID 복사**), 그 대화의 작업 디렉터리에서 실행합니다.

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

Codex는 자체 스레드 ID를 생성하므로, 복사한 값은 Chorus가 제공한 세션 ID가 아니라 그 스레드 ID입니다.
이 값은 Chorus가 실행을 재개할 때 Codex에 다시 전달하는 값과 정확히 같습니다. 전체 흐름은
[세션 중단과 재개](/ko/guides/session-recovery/#터미널에서-이어받기)를 참고하세요.

## 자주 발생하는 문제

- **`codex`를 찾을 수 없음:** `@openai/codex`를 전역으로 설치하고 `chorus agents add`를 다시
  실행합니다.
- **구성 후에도 이전 인증 정보를 쓰거나 `CHORUS_API_KEY`가 없음**: 실제 `CODEX_HOME`의 `.env`를 확인하고 `chorus agents add --agents codex`를 다시 실행한 뒤 위의 안전한 App Server 재시작을 따르세요. 키가 잘못되거나 폐기된 경우에만 교체하세요.
- **플러그인 또는 훅이 비활성화됨:** `/plugins`와 `/hooks`에서 활성화한 뒤 Codex를 재시작합니다.
- **데몬이 오프라인:** `chorus daemon status`를 실행한 뒤
  [에이전트 연결 문제 해결](/ko/guides/troubleshooting/)을 참고합니다.