acodex
License: MIT
Codex 데스크톱 앱을 위한 로컬 MCP 자동화.
acodex는 스크립트, 도구 및 에이전트에 실행 중인 Codex 데스크톱 세션으로 연결되는 로컬 브리지를 제공합니다. acodex를 사용하면 Chrome DevTools Protocol (CDP) 포트를 사용하여 Codex를 재실행하고, 관리형 HTTP/MCP 서버를 실행하며, Codex 데스크톱 빌드가 노출하는 라이브 codex_app.* 도구를 호출할 수 있습니다.
Quick Start | CLI | Support | Contributing
acodex를 사용해야 하는 이유 (Why acodex)
- 실시간 Codex 데스크톱 접근. CDP 플러그인(plumbing)을 작성할 필요 없이 실행 중인 데스크톱 렌더러가 노출하는 도구를 검사하고 호출할 수 있습니다.
- MCP 호환 로컬 서버. 로컬 자동화 클라이언트를 위해
/mcp에서 Codex 데스크톱 도구를 노출합니다.
- 실용적인 CLI 워크플로우. 터미널에서 설정을 확인하고, CDP를 사용하여 Codex를 재실행하며, 브리지를 관리하고, 도구를 호출할 수 있습니다.
Quick Start (빠른 시작)
사전 요구 사항:
- Python 3.10 이상 버전.
uv; 공식 설치 가이드 참조.- Codex.app이 설치된 macOS. 재실행 흐름은 기본적으로
/Applications/Codex.app을 예상하므로, 위치가 다를 경우 ACODEX_CODEX_APP_PATH를 설정해야 합니다.
CLI 설치:
설정을 초기화하고, CDP를 사용하여 Codex를 실행하며, 로컬 브리지를 시작합니다:
acodex config init
acodex codex relaunch --yes
acodex server start
acodex codex relaunch --yes는 acodex가 기본 CDP 엔드포인트인 http://127.0.0.1:45217에 도달할 수 있도록 Codex를 시작하거나 재시작합니다.
서버가 실행된 후 더 깊은 진단이 필요하면, acodex doctor --deep을 사용하십시오.
Codex 데스크톱 도구를 나열하고 호출합니다:
acodex tools list
acodex tools call codex_app.list_threads --limit 1
작업이 완료되면 관리형 브리지를 중지합니다:
CLI (명령줄 인터페이스)
일반 명령어:
acodex config path
acodex config show
acodex doctor --deep
...
도구 호출은 MCP 스키마 속성 이름을 사용합니다. 간단한 최상위 인수는 플래그로 전달하거나, 중첩된 입력을 위해 JSON을 사용하십시오.
acodex tools call codex_app.list_threads --limit=5
acodex tools call --args-json '{"limit":5}' codex_app.list_threads
acodex tools call --output json codex_app.list_threads --limit 5
구성 (Configuration)
acodex는 기본적으로 ~/.acodex/config.json에서 JSON 설정을 읽습니다. 다른 파일을 사용하려면 ACODEX_CONFIG를 설정하세요. 활성 경로 및 유효 값을 확인하려면 acodex config path와 acodex config show를 사용하세요.
필수 로컬 엔드포인트:
- Codex CDP:
http://127.0.0.1:45217
- 관리 서버 상태 (Managed server health):
http://127.0.0.1:45218/healthz
- MCP 엔드포인트:
http://127.0.0.1:45218/mcp
구성 우선순위 및 전체 기본값 매트릭스는 CONTRIBUTING.md에 있습니다.
상태를 변경하는 도구 호출은 운영 중인(live) Codex 데스크톱 앱을 수정합니다. 생소한 도구를 호출하기 전에 acodex tools call <tool> --help를 사용하세요.
지원 (Support)
설정에 실패하면 내장 진단 및 관리 서버 로그부터 시작하세요:
acodex doctor
acodex server logs --tail 50
문제가 지속되면 시도한 내용, 발생한 현상, 사용 중인 OS 및 Python 버전, acodex 소스 브랜치 또는 커밋, Codex 데스크톱/CDP 설정, 그리고 비밀 정보가 제거된 관련 명령어 출력을 포함하여 GitHub issue를 여세요.
기여 (Contributing)
기여자 설정, 아키텍처 노트, 품질 게이트 및 문서화 규칙은 CONTRIBUTING.md에 있습니다. 에이전트별 지침은 AGENTS.md에 있습니다.
라이선스 (License)
acodex는 MIT License 하에 배포됩니다.
OpenAI가 보증합니다.
