GitHub - Mineru98/codex: Lightweight coding agent that runs in your terminal

Mineru98/codex 프로젝트는 터미널에서 실행되는 경량 코딩 에이전트로, OpenAI의 Codex에서 포크된 버전입니다. 이 프로젝트는 개발자가 터미널 환경 내에서 ChatGPT 수준의 추론 능력과 코드 실행, 파일 조작, 반복 작업 등을 Git 버전 관리와 함께 수행할 수 있도록 지원하는 것을 목표로 하는 "채팅 기반 개발(chat-driven development)" 도구입니다.

주요 특징으로는 OpenAI API 키만 있으면 추가 설정 없이 바로 사용할 수 있는 제로 셋업(Zero setup), 네트워크 비활성화 및 디렉토리 샌드박스(directory-sandboxed) 환경에서 안전하게 자동 승인(auto-approval) 기능을 제공하는 점, 그리고 향후 스크린샷이나 다이어그램을 통해 기능을 구현할 수 있는 멀티모달(Multimodal) 지원이 있습니다. 프로젝트는 Apache-2.0 라이선스 하에 오픈소스(open-source)로 개발 중이며, 버그 리포트, 기능 요청, Pull Request 등 커뮤니티의 기여를 환영합니다.

핵심 방법론 (Core Methodology): 보안 모델 및 플랫폼 샌드박싱

Codex는 --approval-mode 플래그를 통해 에이전트의 자율성 수준과 자동 승인 정책을 사용자가 결정할 수 있도록 합니다.
* Suggest (기본값): 저장소 내 모든 파일을 읽을 수 있지만, 파일 쓰기/패치, 임의의 쉘 명령어 실행 시 사용자 승인이 필요합니다.
* Auto Edit: 파일에 대한 쓰기 및 패치 적용은 자동으로 수행하지만, 모든 쉘 명령어는 승인이 필요합니다.
* Full Auto: 파일을 읽고 쓸 수 있으며, 쉘 명령어를 실행할 수 있습니다. 이 모드에서는 모든 명령어가 네트워크 비활성화(network-disabled) 상태로 실행되고, 현재 작업 디렉토리(current working directory)와 임시 파일(temporary files)로 제한되는 방어적 심층 보안(defense-in-depth)이 적용됩니다. Git으로 추적되지 않는 디렉토리에서 Auto Edit 또는 Full Auto 모드로 시작할 경우 경고/확인 메시지가 표시되어 안전망을 제공합니다.

플랫폼 샌드박싱(Platform Sandboxing) 상세:
Codex는 운영 체제에 따라 다른 강화 메커니즘을 사용합니다.
* macOS 12+: Apple Seatbelt (sandbox-exec)를 사용하여 명령어를 래핑합니다. __INLINE_FORMULA_0__(TMPDIR), ~/.codex 등을 제외한 모든 경로를 읽기 전용(read-only) Jailed 환경에 배치합니다. 아웃바운드 네트워크(Outbound network)는 기본적으로 완전히 차단됩니다.
* Linux: 기본 샌드박싱이 제공되지 않습니다. 대신 Docker 사용을 권장합니다. Codex는 최소한의 컨테이너 이미지(minimal container image) 내에서 자체적으로 실행되며, 사용자의 저장소(repo)를 컨테이너 내부에 읽기/쓰기 권한으로 마운트합니다. 사용자 정의 iptables / ipset 방화벽 스크립트가 OpenAI API를 제외한 모든 이그레스(egress)를 거부합니다. 이는 호스트에 root 권한 없이도 결정론적(deterministic)이고 재현 가능한(reproducible) 실행 환경을 제공합니다. run_in_container.sh 스크립트를 통해 샌드박스를 설정할 수 있습니다.
* Windows: 직접 지원하지 않으며, WSL2(Windows Subsystem for Linux 2)를 통해 실행됩니다.

구성 및 사용:
사용자는 ~/.codex/config.yaml 또는 ~/.codex/config.json 파일을 통해 모델(model), 승인 모드(approvalMode), full-auto 모드에서의 오류 처리(fullAutoErrorMode), 알림 활성화 여부(notify) 등을 설정할 수 있습니다. 또한 providers 객체를 통해 OpenAI, Azure OpenAI, OpenRouter, Gemini, Ollama, Mistral 등 다양한 AI 서비스 제공자를 구성할 수 있으며, 각 제공자는 name, baseURL, API 키를 위한 envKey를 가집니다. history 객체에서는 대화 기록의 최대 크기, 저장 여부 및 민감한 패턴 필터링을 설정할 수 있습니다. API 키는 환경 변수(OPENAI_API_KEY 등)로 설정해야 합니다.

AGENTS.md 파일을 통해 에이전트에 대한 사용자 정의 지침(Custom instructions)을 제공할 수 있으며, 이 파일은 ~/.codex/AGENTS.md, 저장소 루트의 AGENTS.md, 현재 작업 디렉토리의 AGENTS.md 순서로 병합됩니다.

사용 예시(Recipes):
codex "Refactor the Dashboard component to React Hooks"와 같은 명령어를 통해 코드 리팩토링, SQL 마이그레이션 생성, 유닛 테스트(unit tests) 작성, 파일명 일괄 변경, 정규식 설명, PR 제안, 보안 취약점 분석 등 다양한 작업을 수행할 수 있습니다.

기여 및 개발:
프로젝트는 활발히 개발 중이며, 기여자를 환영합니다. Git hooks(Husky)를 통해 코드 품질 검사(pre-commit, pre-push)를 강제하며, Vitest로 유닛 테스트, ESLint + Prettier로 스타일, TypeScript로 타입 검사를 수행합니다. Pull Request를 제출할 때는 상세한 설명과 함께 테스트 커버리지를 포함하고, CLA(Contributor License Agreement)에 서명해야 합니다. Nix flake를 통한 개발 환경 설정 및 빌드 옵션도 제공됩니다. 보안 취약점 발견 시에는 security@openai.com으로 이메일 연락을 요청합니다.