참고자료 · Codex Setup
Codex 도입 패턴과 설치 가이드
좋은 문서는 “기능이 있다”에서 끝나지 않고 “그래서 내 저장소에는 무엇을 어디에 넣으면 되는가”까지 내려와야 합니다. 이 페이지는 그런 관점에서, Codex 하네스를 새 저장소에 들여올 때 가장 실용적인 설치 패턴만 추려 정리한 가이드입니다.
1. 어떤 설치 패턴이 있나
최소 설치
AGENTS.md + config.toml + 기본 verify 명령만 먼저 둡니다. 개인 실험이나 작은 저장소에 적합합니다.
표준 설치
rules, hooks, reviewer/verifier subagent, 2~3개 skill을 추가합니다. 팀 공통 기본값으로 가장 무난합니다.
확장 설치
MCP, 팀별 subagent, rollout 가드레일, 관측성까지 붙입니다. 플랫폼 저장소나 멀티모듈 저장소에 적합합니다.
2. 최소 설치
처음에는 두 파일만 있어도 충분합니다. 핵심은 모델보다 검증 명령을 먼저 고정하는 것입니다.
my-project/
├── AGENTS.md
└── .codex/
└── config.toml# AGENTS.md
- 작업 전 README 와 docs/ 를 먼저 읽습니다.
- 완료 기준은 빌드, 테스트, 린트 결과를 확인한 뒤 요약하는 것입니다.
- 위험 명령과 외부 반영 작업은 사용자 확인을 거칩니다.
## 검증
- Kotlin: source ~/.zshrc >/dev/null 2>&1 && export GRADLE_USER_HOME="$PWD/.gradle-user" && ./gradlew ktlintCheck test --no-daemonmodel = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false3. 표준 설치
팀에서 계속 쓰려면 여기까지는 올리는 편이 좋습니다. 특히 rules 와 hooks 가 들어와야 “실수 방지”가 생깁니다.
my-project/
├── AGENTS.md
├── .codex/
│ ├── config.toml
│ ├── hooks.json
│ ├── hooks/
│ │ ├── session_start_context.py
│ │ ├── pre_bash_guard.py
│ │ └── post_kt_lint.sh
│ ├── rules/
│ │ └── default.rules
│ ├── agents/
│ │ ├── reviewer.toml
│ │ └── gradle-verifier.toml
│ └── skills/
│ ├── review/SKILL.md
│ └── gradle/SKILL.md
└── scripts/
└── verify_codex_harness.sh4. 필요한 것만 선택 설치하는 방법
참고 사이트에서 가장 좋았던 점 중 하나가 “전체 복사” 대신 “필요한 것만 가져오기”를 강조한다는 점입니다. 우리도 같은 방식으로 보는 것이 좋습니다.
reviewer만 먼저
코드 리뷰와 post-change validation 니즈가 가장 먼저 있으면 reviewer subagent와 review skill만 먼저 넣습니다.
hooks만 먼저
파괴 명령 차단과 수정 직후 ktlintCheck 같은 guardrail이 급하면 hooks와 rules부터 넣습니다.
MCP만 먼저
문서 grounding이나 브라우저 검증이 급하면 Context7, Playwright MCP부터 먼저 붙입니다.
verify 스크립트만 먼저
팀의 공통 신뢰 기반이 약하면 verify 스크립트를 먼저 표준화한 뒤 나머지 하네스를 얹는 편이 좋습니다.
5. copy-ready 전체 예시
model = "gpt-5.4"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false
[features]
codex_hooks = true
multi_agent = true
experimental_use_rmcp_client = true
[profiles.review]
model = "gpt-5.4-mini"
sandbox_mode = "read-only"
[agents.reviewer]
config_file = "agents/reviewer.toml"
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest", "--headless"]prefix_rule(["git", "reset", "--hard"], "forbidden")
prefix_rule(["rm", "-rf"], "forbidden")
prefix_rule(["terraform", "destroy"], "forbidden")
prefix_rule(["kubectl", "delete"], "forbidden")
prefix_rule(["git", "push"], "prompt")
prefix_rule(["gh", "pr", "create"], "prompt"){
"hooks": {
"SessionStart": [
{
"command": "/usr/bin/python3 $(git rev-parse --show-toplevel)/.codex/hooks/session_start_context.py"
}
],
"PreToolUse": [
{
"matcher": "Bash",
"command": "/usr/bin/python3 $(git rev-parse --show-toplevel)/.codex/hooks/pre_bash_guard.py"
}
]
}
}6. 문제 해결 패턴
설정이 적용되지 않는 것 같을 때
먼저 작업 디렉터리가 프로젝트 루트인지 확인하고, 그다음 .codex/config.toml 위치와 문법을 봅니다.
hooks가 안 도는 것 같을 때
[features] codex_hooks = true, hooks.json 위치, matcher, stdin payload 파싱을 순서대로 봅니다.
MCP가 연결되지 않을 때
원격 MCP는 OAuth나 네트워크 문제일 수 있고, stdio MCP는 command/args 오류일 가능성이 큽니다. 두 경우를 분리해서 봐야 합니다.
Gradle이 자꾸 환경 문제를 낼 때
저장소 로컬 캐시와 셸 초기화를 명시적으로 맞춥니다. 보통 source ~/.zshrc 와 GRADLE_USER_HOME 고정으로 해결됩니다.