Codex

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

설치 전에 에이전트 액세스 준비에 따라 에이전트 키를 만드세요.

통합 설치

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

npm install --global @openai/codex

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

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를 사용한다면 이 섹션을 건너뛰세요. 그렇지 않다면 에이전트 런타임 연결에 따라 백엔드로 codex를 선택합니다. Chorus 데몬 운영으로 온라인 상태를 유지하기 전에, 포그라운드에서 연결을 확인하세요.

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로 명시적인 포그라운드 명령을 실행하세요. 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)에 다음과 같이 도구 허용을 명시하세요.

[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으로 종료되더라도 성공이 아닙니다. 복구 절차는 세션 중단과 재개를 참고하세요.

연결 확인

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

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

기능과 제한

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

공통 운영 절차는 원격 에이전트에서 작업 시작과 세션 중단과 재개를 사용하세요.

터미널에서 재개하기

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

codex exec resume <thread_id>

Codex는 자체 스레드 ID를 생성하므로, 복사한 값은 Chorus가 제공한 세션 ID가 아니라 그 스레드 ID입니다. 이 값은 Chorus가 실행을 재개할 때 Codex에 다시 전달하는 값과 정확히 같습니다. 전체 흐름은 세션 중단과 재개를 참고하세요.

자주 발생하는 문제

• 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를 실행한 뒤 에이전트 연결 문제 해결을 참고합니다.