MCP

작전 지휘부 codex-cc-orchestrator: Codex가 Claude Code에 작업을 지시해 실행·검토하게 하기

작전 지휘부는 Codex가 코딩 작업을 Claude Code에 지시하여 실행하고 독립된 읽기 전용 세션이 검토하도록 하는 데 가장 적합하지만, 신뢰할 수 있는 project_root를 명시적으로 전달하고 두 Agent를 모두 설치해야 한다는 전제가 필요합니다.

Official source · 点将台 codex-cc-orchestrator

Install

git clone https://github.com/zjgxkj/codex-cc-orchestrator.git && cd codex-cc-orchestrator && git checkout v0.4.0 && uv sync

작전 지휘부(codex-cc-orchestrator)는 하나의 메인 Agent가 작업을 실행자에게 지시(dispatch)하고, 이후 독립된 읽기 전용 세션이 검토하는 흐름이 필요한 경우에 적합합니다. 시작하기 전 가장 중요한 점: Codex와 Claude Code 두 로컬 Agent를 모두 설치하고 구성해야 하며, 각 작업마다 신뢰할 수 있는 project_root를 명시적으로 전달해야 합니다. 서비스는 현재 디렉터리를 기준으로 워크스페이스를 추측하지 않습니다.

누구에게 적합한가

  • 이미 Codex를 사용 중이고 Claude Code를 설치한 사용자로, MCP를 통해 작업을 Claude Code에 지시하여 실행·검토하도록 하고 계층화된 협업 오케스트레이션을 원하는 경우.
  • 작업 지시, 실행, 재개, 독립 검토, 결과 압축, 사용량 기록이 필요한 개발 워크플로.
  • 부적합한 경우: Codex와 Claude Code 양쪽 환경을 동시에 갖추지 못한 사람. 한쪽만 단독으로 사용할 수 있는지는 자료에서 확인되지 않으므로 공식 문서를 기준으로 하십시오.
  • 사용 전제: 로컬에 Python 3.13+와 uv가 필요합니다. 전체 설치 절차(중국어)는 공식 INSTALL.md를 참고하세요.

3분 만에 첫 시도 완료하기

전제 조건: Python 3.13+, uv, 그리고 구성이 완료된 Codex와 Claude Code.

  1. 가져와서 설치(공식 기본 경로):
git clone https://github.com/zjgxkj/codex-cc-orchestrator.git
cd codex-cc-orchestrator
git checkout v0.4.0
uv sync
  1. Codex의 STDIO MCP 구성에 서비스 등록(Windows 공식 예시):
[mcp_servers.codex-claude-agent]
command = 'D:\path\to\codex-claude-agent-mcp\.venv\Scripts\python.exe'
args = ['-m', 'codex_claude_agent_mcp']
enabled = true
startup_timeout_sec = 30
tool_timeout_sec = 7200
  1. 저위험 첫 시도: 서비스는 ping 도구를 노출하므로, 이를 사용해 MCP 채널 연결을 확인할 수 있으며 어떤 파일 쓰기도 발생하지 않습니다. 성공 신호는 Codex가 서비스 도구 목록을 조회하고 ping 응답을 수신하는 것입니다. 참고로 stdout은 MCP 프로토콜 메시지만 전달하고, 로그와 오류는 모두 stderr에 출력됩니다. 시작 문제를 디버깅할 때는 stderr를 확인하세요.

실제 작업 실행(execute_task 등)은 별개의 문제입니다: 신뢰하는 project_root를 반드시 명시적으로 전달해야 하며, 실행은 해당 디렉터리 내 파일을 읽고 쓰는 실제 부작용이 있는 작업입니다. 호출 전에 대상 프로젝트 디렉터리를 확인하십시오.

사용 사례

사례 1: 코딩 작업을 지시하고 실행. Codex 세션에서 execute_task를 호출하고 작업 설명과 명시적으로 승인한 project_root를 전달합니다. 실행자 세션은 제한된 도구 집합(Read/Grep/Glob/Edit/Write/Bash, 네트워크 허용, 중첩 Agent와 노트북 편집은 금지)으로 변경을 수행합니다. 기대 결과: 작업이 실행되고 상태가 로컬 SQLite(~/.codex-claude-agent-mcp/state.db)에 저장됩니다.

사례 2: 독립 검토와 재개. review_task를 호출하면 완전히 새로운 읽기 전용 세션이 실행 결과를 검토하고 PASS/FAIL을 제시합니다. FAIL인 경우, continue_task를 호출해 저장된 실행 세션을 기반으로 피드백을 반영하여 이어서 진행할 수 있습니다. 기대 결과: 읽기 전용 검토는 파일을 변경하지 않으며, 재개 시 세션 컨텍스트를 재사용합니다. 또한 run_job / run_jobs로 여러 작업을 오케스트레이션하고 get_job_status로 진행 상황을 조회할 수 있습니다.

사용 경계

  • 읽기/쓰기 특성: ping은 읽기 전용 연결 확인입니다. execute_task, run_job, run_jobs는 project_root 아래의 파일을 쓰는 실제 부작용이 있으므로 호출 전에 디렉터리가 올바른지 확인해야 합니다. review_task는 읽기 전용 세션이 검토를 수행합니다.
  • 권한 부여: 각 작업은 project_root를 받을 수 있으며, Codex는 신뢰할 수 있는 workspace root를 반드시 명시적으로 전달해야 합니다. 서비스는 자신의 프로세스 cwd를 근거로 추측하지 않습니다. ALLOWED_PROJECT_ROOTS는 선택적인 장기 신뢰 목록입니다.
  • 로컬 상태: 실행 세션 등의 상태는 ~/.codex-claude-agent-mcp/state.db에 저장됩니다. 공식적으로 이 상태의 삭제 또는 철회 경로는 안내되어 있지 않습니다.
  • 동시성 제한: CLAUDE_MAX_CONCURRENCY(기본값 4)는 단일 MCP server 프로세스에만 적용됩니다.
  • 도구의 읽기 전용 표시는 쓰기 작업을 수행하지 않는다는 의미일 뿐, 네트워크 접속이 없거나 개인정보 경계가 없다는 뜻이 아닙니다. 공식적으로 설명되지 않은 부분(예: 자격 증명 관리 세부 사항)은 무위험으로 간주해서는 안 됩니다.