공식 참고 자료: Sandboxing · Config Basics · Cloud Environments · Review
커리큘럼 흐름
- Codex 시작하기 — 설치, 첫 작업, 체크포인트까지 — 입문 루프
- Codex 지시문 — AGENTS.md를 진짜 쓸모 있게 만드는 법 — 저장소 규칙
- Codex 샌드박싱 — 권한, 승인, 클라우드 환경 이해하기 — 권한과 승인 ← 현재 문서
- Codex 작업 설계 — 소원 말고 이슈처럼 프롬프트 쓰기 — 좋은 task shape 만들기
- Codex Skills — 반복 프롬프트를 재사용 가능한 워크플로우로 바꾸기 — 반복 워크플로우를 재사용 자산으로 만들기
- Codex 서브에이전트 — 병렬 실행과 위임 패턴 — 병렬 실행과 위임
- Codex MCP — 외부 컨텍스트를 복붙 대신 연결하기 — 외부 시스템 연결
- Codex 리뷰와 자동화 — /review, worktree, 반복 엔지니어링 운영하기 — 반복 작업 운영
- Codex Worktrees — 브랜치 충돌 없이 병렬 실행하기
- Codex 핸드오프 — 병렬 레인을 머지 가능한 결과로 연결하기
- Codex 검증 루프 — 머지 전에 동작을 증명하기
- Codex 릴리스 준비도 — 프로덕션 전 최종 게이트
- Codex 첫날 안전 루프 — 초반 실수를 줄이는 입문 워크플로우
- Codex 팀 딜리버리 플레이북 — 중급 레인 운영
- Codex 고위험 변경 거버넌스 — 크리티컬 릴리스를 위한 고급 통제
- Codex 운영 매뉴얼 — 팀의 일/주/릴리스 리듬 정렬하기
- Codex 사고 복구 플레이북 — 프로덕션 압박 상황에서의 결정론적 대응
- Codex 사고 후 하드닝 루프 — 복구를 내구성 있는 통제로 전환하기
- Codex 카오스 복원력 드릴 — 실패가 오기 전에 리허설하기
- Codex 복원력 지표와 SLO — 실패 전에 신뢰성을 측정하기
- Codex Ralph 지속 루프 — 긴 작업을 검증 가능한 완료까지 가져가기
이 문서에서 참고한 공식 문서
read-only,workspace-write,danger-full-access의 차이 — Sandboxing- 기본 config 조합과 approval/sandbox 해석 — Config basics
- cloud task의 setup script와 인터넷 적용 순서 — Cloud environments
- review 범위를 uncommitted changes, branch diff, last turn, staged/unstaged로 바꾸는 방식 — Review
핵심 원칙: 샌드박스는 보안 장치이자 UX 장치다
샌드박스를 “막는 기능”으로만 보면 설정이 자꾸 극단으로 갑니다. 너무 좁히면 승인 요청이 계속 떠서 흐름이 끊기고, 너무 넓히면 작은 실수의 반경이 커집니다.
좋은 설정의 목적은 하나입니다. Codex가 정상적인 작업은 계속 진행하게 하면서, 진짜 위험한 경계만 사람이 직접 확인하게 만드는 것입니다.
그래서 샌드박스는 단순 보안 옵션이 아니라, 실제 작업 경험을 결정하는 운영 옵션이기도 합니다.
세 가지를 같이 봐야 한다
권한 체계는 보통 아래 세 가지를 함께 봐야 이해가 됩니다.
| 축 | 질문 | 잘못 맞추면 생기는 일 |
|---|---|---|
| sandbox mode | 어디까지 읽고/쓸 수 있나 | 작업 자체가 막히거나 반대로 과도하게 넓어짐 |
| approval policy | 언제 사람 허가를 받나 | 승인 피로 또는 무방비 자동 실행 |
| writable roots | 정확히 어떤 경로를 쓸 수 있나 | 무관한 파일 수정, 홈 디렉터리 오염 |
sandbox mode만 맞추고 나머지를 대충 두면 실제 체감은 오히려 나빠질 수 있습니다.
로컬과 cloud는 다른 문제다
많은 입문자가 “Codex가 왜 막히는지”를 이해하지 못하는 이유는 로컬과 cloud를 같은 시스템처럼 생각하기 때문입니다.
로컬 Codex
- 내 머신에서 실행된다
- sandbox mode와 approval policy를 내가 조절한다
- writable roots 경계가 매우 중요하다
Cloud Codex
- OpenAI가 관리하는 컨테이너에서 실행된다
- setup script, environment variables, 인터넷 정책이 핵심이다
- 로컬에만 있던 숨은 상태가 쉽게 드러난다
문제가 생겼을 때 가장 먼저 물어볼 질문은 이것입니다.
지금 막힌 이유가 로컬 권한 문제인가, cloud 재현성 문제인가?
이걸 분리해서 생각하면 원인 파악 속도가 훨씬 빨라집니다.
로컬 sandbox mode 세 가지
공식 Sandboxing 문서를 기준으로 로컬에서 자주 보는 모드는 아래와 같습니다.
| 모드 | 의미 | 잘 맞는 작업 |
|---|---|---|
read-only |
파일 탐색 중심. 수정이나 많은 명령은 승인 경계에 걸리기 쉽다 | 감사, 조사, 안전한 코드 리뷰 |
workspace-write |
워크스페이스 안 수정과 일반적인 명령 실행에 적합하다 | 대부분의 일상 개발 |
danger-full-access |
샌드박스 제한을 제거한다 | 높은 신뢰도의 자동화, 매우 제한적인 특수 상황 |
실전 기본값은 대개 workspace-write입니다.
탐색은 자유롭고, 저장소 안 작업도 자연스럽게 이어지며, 그래도 경계는 남아 있기 때문입니다.
approval policy는 “멈추는 시점”을 정한다
Best Practices와 Config Basics를 같이 보면, 권한 운영에서 중요한 건 단순 허용/차단이 아니라 언제 멈추게 할지입니다.
대표적인 감각은 이렇습니다.
| approval policy 감각 | 언제 맞는가 | 대가 |
|---|---|---|
| tight / 자주 묻기 | 첫 도입, 낮은 신뢰의 저장소, 민감 영역 | 안전하지만 흐름이 자주 끊김 |
on-request 중심 |
대부분의 팀 기본값 | 일상 작업은 이어지고 경계만 확인 |
| 거의 안 묻기 | 이미 검증된 자동화, 매우 좁은 실행 범위 | 빠르지만 review와 rollback discipline이 더 중요 |
처음에는 approval과 sandbox를 타이트하게 두고, 진짜 병목이 승인 피로인지 확인한 뒤에만 완화하는 편이 좋습니다.
현실적인 로컬 기본 조합
문서와 실무 감각을 합치면 입문자에게 가장 무난한 기본 조합은 아래에 가깝습니다.
approval_policy = "on-request"
sandbox_mode = "workspace-write"그리고 writable roots는 저장소 중심으로 최소화합니다. 이 조합의 장점은 다음과 같습니다.
- 저장소 안 일반 작업은 대체로 계속 진행됨
- 경계를 넘는 순간에는 사람이 개입할 수 있음
- 승인 피로와 위험도 사이의 균형을 맞추기 쉬움
writable roots가 진짜 사고 반경을 정한다
많은 사용자가 sandbox mode는 보지만 writable roots는 대충 둡니다. 실제로는 writable roots가 사고 반경을 더 직접적으로 정합니다.
좋은 기본값
- 현재 저장소 루트
- 정말 필요할 때만 임시 디렉터리 한 곳
위험한 기본값
- 홈 디렉터리 전체
- 서로 무관한 여러 프로젝트 루트
- 오래된 실험 폴더까지 한 번에 열어둔 상태
질문은 “Codex가 쓸 수 있는가?”가 아니라 **“정확히 어디까지 쓸 수 있는가?”**여야 합니다.
cloud에서는 setup이 계약이다
Cloud Environments 문서의 핵심은 단순합니다. cloud task는 “깨끗한 컨테이너 + 선언된 setup + 제한된 실행 단계”라는 계약 위에서 돌아갑니다.
대표 흐름은 아래처럼 이해하면 편합니다.
- 컨테이너 준비와 저장소 checkout
- setup script 실행
- 인터넷 정책 적용
- agent phase에서 수정·검증
여기서 중요한 포인트:
- setup 단계는 환경을 재현 가능하게 만드는 곳이다
- 설치, codegen, 테스트 데이터 준비 같은 선행 작업을 setup으로 밀어 넣는 편이 안정적이다
- agent phase에서는 “문제 해결과 검증”에 집중시키는 게 좋다
setup script에 넣을 것과 넣지 말 것
setup에 잘 맞는 것
- 의존성 설치
- 런타임/툴 버전 고정
- 테스트 데이터 준비
- codegen
- 네이티브 빌드 사전 준비
setup에 과한 것
- feature 구현 자체
- 장시간 판단이 필요한 단계
- 사람이 중간중간 봐야 하는 복잡한 운영 절차
setup은 환경을 예측 가능하게 만드는 단계이지, 기능을 몰래 완성하는 단계가 아닙니다.
review는 권한을 넓힐수록 더 중요해진다
Review 문서 기준으로 review pane은 기본적으로 현재 작업 트리의 변경을 다시 보는 장치입니다. 범위를 바꿔서 아래처럼 볼 수 있습니다.
- uncommitted changes
- all branch changes
- last turn changes
- staged / unstaged
이게 샌드박스와 연결되는 이유는 분명합니다. 권한이 넓어질수록 승인 횟수는 줄지만, 나중에 사람이 다시 볼 책임은 커집니다.
즉,
- 좁은 권한 = 흐름 느림, 위험 반경 작음
- 넓은 권한 = 흐름 빠름, review와 checkpoint 책임 큼
둘은 늘 세트로 움직입니다.
로컬에서 막힐 때 보는 진단 순서
권한 문제가 의심될 때는 아래 순서가 좋습니다.
- 지금 막힌 것이 파일 쓰기 문제인지, 명령 실행 문제인지 확인
- sandbox mode가 너무 좁은지 본다
- approval policy가 불필요하게 자주 멈추는지 본다
- writable roots에 실제 경로가 포함되어 있는지 본다
- 권한을 넓히기 전에
/review와 Git checkpoint 습관이 있는지 본다
권한을 바로 올리기보다 막히는 원인을 분해하는 편이 결과가 좋습니다.
흔한 실패 패턴과 대응
| 증상 | 자주 있는 원인 | 먼저 할 대응 |
|---|---|---|
| 승인 요청이 계속 뜬다 | read-only가 과도하거나 roots가 좁다 |
workspace-write 또는 roots 범위를 재검토 |
| 로컬에서는 되는데 cloud에서 실패한다 | 숨은 로컬 상태가 setup에 없다 | setup script와 환경 변수 의존성을 명시 |
| 실행은 빨라졌는데 불안하다 | 권한만 넓히고 review/checkpoint를 안 붙였다 | /review, Git checkpoint, diff 확인 루틴 추가 |
| unrelated 파일까지 건드린다 | writable roots가 너무 넓다 | 루트를 저장소 중심으로 다시 좁힘 |
| setup이 오래 걸리고 자주 실패한다 | setup에 feature 구현이나 비결정적 단계가 섞였다 | 설치/준비와 구현 단계를 분리 |
팀 운영 기준을 미리 정하면 덜 흔들린다
샌드박스 문제는 개인 취향처럼 보여도, 팀에서는 운영 기준이 없을수록 흔들립니다. 예를 들면 이런 기준이 좋습니다.
- 신규 저장소는 default permissions로 시작
- 승인이 병목이라는 근거가 생길 때만 완화
- writable roots는 저장소 단위로 최소화
- 넓은 권한 프로필은
/review와 checkpoint를 필수 루틴으로 둠 - cloud 작업은 setup script와 검증 명령을
AGENTS.md에 명시
이 기준이 있으면 “왜 이 저장소는 느슨하고 저 저장소는 엄격한가”가 설명됩니다.
빠른 운영 체크리스트
로컬
workspace-write부터 시작했는가?- approval policy가 과하게 잦지 않은가?
- writable roots가 저장소 중심으로 좁은가?
- 작업 후
/review또는 Git diff 확인 루틴이 있는가?
Cloud
- setup script가 재현 가능하고 결정론적인가?
- 설치/부트스트랩이 setup 단계로 분리되어 있는가?
- 시크릿이 최소한으로만 노출되는가?
- 검증 명령이 문서화되어 있는가?
운영 원칙 한 줄 요약
처음엔 좁게 시작하고, 승인 피로가 실제 병목일 때만 단계적으로 넓히세요. 그리고 권한을 넓힌 만큼 review, diff 확인, rollback discipline을 반드시 강화하세요.
좋은 샌드박스 설정은 가장 강한 설정이 아니라, 팀이 안심하고 반복해서 사용할 수 있는 설정입니다.