Codex CLI의 샌드박스와 승인 정책은 두 개의 독립된 축이다 — 그 구조를 알면 대규모 리팩토링을 단계별로 위임할 수 있다

처음 Codex CLI를 팀 워크플로에 도입하면서 저도 같은 실수를 했습니다. auth 모듈 전체를 세션 기반에서 JWT 방식으로 전환하는 작업을 full-auto 모드로 돌리고 잠깐 자리를 비웠는데, 돌아와보니 커밋하지 않은 변경사항 일부가 사라지고 테스트 파일 몇 개가 삭제된 채 새 파일로 덮어써져 있었습니다. git reset --hard로 복구는 했지만 그날 오전 작업이 날아갔습니다.

그때 저는 full-auto를 "에이전트를 완전히 해방시키는 스위치"로 이해하고 있었습니다. 실제로는 달랐습니다. full-auto는 두 개의 독립된 보안 축을 특정 방식으로 묶어놓은 단축 플래그고, 그 두 축을 각각 어떻게 설정하느냐가 에이전트의 실제 동작을 결정합니다. 이 구조를 이해하고 나서야 수백 개 파일에 걸친 리팩토링도 단계를 나눠 위임할 수 있었습니다.

이 글은 AI 코딩 에이전트를 팀 워크플로에 도입하려는 시니어 백엔드·풀스택 개발자를 대상으로, 샌드박스와 승인 정책이 어떻게 독립적으로 작동하는지, suggest → auto-edit → full-auto 세 모드를 어떤 기준으로 선택하는지, AGENTS.md로 팀 컨벤션을 에이전트에 자동 주입하는 방법을 실전 시나리오와 함께 다룹니다.

Codex CLI란

Codex CLI는 OpenAI가 공개한 오픈소스 경량 코딩 에이전트입니다. 터미널에서 o3, o4-mini 같은 최신 모델을 직접 호출해 코드를 읽고, 쓰고, 실행하는 루프를 구성할 수 있습니다. IDE 없이 터미널만으로 동작한다는 점이 백엔드 개발자 입장에서 매력적이고, CI 파이프라인에 직접 편입하거나 MCP 서버로 노출해 멀티 에이전트 파이프라인을 구성하는 것도 가능합니다.

GitHub에서 수만 개의 스타를 받으며 활발하게 개발 중이고, 웹 기반 Codex 앱이 추가된 이후 사용자 기반이 빠르게 성장했습니다.

보안의 두 축: 샌드박스와 승인 정책

Codex CLI의 보안 구조는 하나의 레버가 아니라 두 개의 독립된 축으로 구성됩니다.

샌드박스는 에이전트가 기술적으로 무엇을 할 수 있는지를 OS 수준에서 강제합니다. macOS는 Apple Seatbelt, Linux와 WSL2는 bubblewrap(bwrap)을 사용합니다. 기본 설정은 네트워크 차단과 현재 워크스페이스에만 쓰기를 허용하는 "워크스페이스-쓰기" 모드입니다. 에이전트가 요청을 보내더라도 OS 커널이 그 요청 자체를 막습니다.

승인 정책은 에이전트가 특정 액션을 실행하기 전에 사용자 확인을 요구하는지를 결정합니다. 샌드박스가 "기술적 가능 범위"를 정의한다면, 승인 정책은 "그 범위 안에서 언제 사람에게 물어볼지"를 제어합니다.

두 축이 독립적이라는 말의 실용적 의미는 이렇습니다. 샌드박스를 엄격하게 설정해두면 승인 정책을 느슨하게 운용해도 민감 정보 유출이나 워크스페이스 밖 접근 위험이 줄어듭니다. 반대로 승인 정책이 엄격하더라도 샌드박스가 없으면 에이전트가 실수로 의도치 않은 범위를 건드릴 수 있습니다.

에이전트의 액션은 두 레이어를 순서대로 통과합니다. 샌드박스 레이어를 통과하지 못하면 승인 정책에 도달조차 하지 않습니다.

다이어그램 1

이 순서가 두 레이어를 별도로 구성하는 이유이기도 합니다. 샌드박스는 "가능한 범위"를 정하고, 승인 정책은 그 범위 안에서 "허락 여부"를 결정합니다.

세 가지 모드는 두 축의 프리셋이다

suggest, auto-edit, full-auto는 승인 정책과 샌드박스를 특정 조합으로 묶은 프리셋입니다. 모드 이름이 주는 인상—"점점 자율적이 되는 단일 스케일"—은 실제 구조와 다릅니다.

모드	승인 정책	샌드박스	적합한 상황
`suggest`	모든 액션 승인 요청	기본 적용	태스크 탐색, 프로덕션 첫 적용
`auto-edit`	파일 수정 자동 / 셸 명령 승인	기본 적용	파일 변경은 신뢰하되 셸은 통제
`full-auto`	모든 액션 자동 실행	워크스페이스-쓰기	격리 컨테이너, CI 자동화 루프

--full-auto 플래그가 "단순히 승인 정책을 끄는 것"과 다른 이유가 여기 있습니다. 이 플래그는 승인 정책을 "자동 실행"으로 설정하는 동시에 샌드박스를 "워크스페이스-쓰기"로 명시적으로 구성합니다. 하나의 플래그로 두 축을 함께 설정하는 단축 설정입니다.

두 축을 독립적으로 설정해야 하는 경우—특정 경로만 읽기 차단하거나, 네트워크는 허용하되 셸 명령은 항상 승인받도록 하는 등—은 ~/.codex/config.toml에서 각각 구성할 수 있습니다.

Codex CLI에 전달하는 프롬프트는 영어로 작성하는 것이 결과 일관성 면에서 더 안정적입니다. 아래 코드 예시도 영어 프롬프트를 기준으로 작성했습니다.

bash

# 모드별 사용 예시
codex --approval-mode suggest "Review the auth module refactoring plan and list affected files"
codex --approval-mode auto-edit "Add error handling to all service layer functions"
 
# 반드시 격리 컨테이너 또는 throw-away 브랜치에서 실행
codex --full-auto "Run tests and fix any failures, then verify with another test run"

AGENTS.md: 팀 표준을 에이전트에 주입하기

Codex는 작업 시작 전에 AGENTS.md 파일을 읽습니다. 전역(~/.codex/AGENTS.md)과 프로젝트 루트 수준에서 계층적으로 로드되며, 두 파일의 내용이 병합되어 에이전트에게 전달됩니다.

구두로 전달하던 코딩 가이드라인을 AGENTS.md에 정의해두면 에이전트가 매 태스크마다 팀 컨벤션을 자동으로 따르게 됩니다. 코드 리뷰에서 반복적으로 지적되는 패턴을 금지 규칙으로 등록해두는 것도 효과적입니다.

markdown

# AGENTS.md 예시 (프로젝트 루트)
 
## 코딩 표준
- TypeScript strict 모드 유지
- 모든 async 함수에 try-catch 포함
- 테스트 파일은 __tests__/ 디렉터리에
 
## 금지 패턴
- console.log 직접 사용 금지 (logger 사용)
- any 타입 사용 금지
 
## 워크플로
- 변경 전 반드시 현재 테스트 커버리지 확인
- 변경 후 npm test 실행 필수

--print-instructions 플래그로 실제로 로드된 AGENTS.md 병합 내용을 확인할 수 있습니다. 설정이 제대로 주입되고 있는지 검증할 때 유용합니다.

파일시스템 보안: deny-read 정책

~/.codex/config.toml의 deny_read 설정은 특정 경로에 대한 읽기 자체를 차단합니다. 샌드박스 레이어의 기본 설정이 쓰기 범위를 제한한다면, deny-read는 읽기 범위를 명시적으로 좁히는 추가 설정입니다.

toml

# ~/.codex/config.toml
[sandbox]
deny_read = [
  ".env",
  ".env.*",
  "**/*.pem",
  "**/credentials.json",
  "~/.ssh/**"
]

프롬프트 인젝션 공격이나 에이전트의 실수로 자격 증명 파일이 노출되는 시나리오를 원천 차단할 수 있습니다. 전역 config에 한 번만 설정해두면 모든 프로젝트에 적용됩니다.

실전 적용

시나리오 1: auth 미들웨어 리팩토링 — 3단계 점진적 위임

실무에서 가장 많이 쓰는 패턴은 suggest → auto-edit → full-auto 순서로 단계를 올려가는 방식입니다. 단계마다 결과를 확인하며 신뢰를 쌓아갑니다.

다이어그램 2

bash

# Step 1: suggest 모드로 리팩토링 범위 먼저 확인
codex --approval-mode suggest \
  "Refactor the auth middleware from session-based to JWT. \
   Show the list of affected files and the planned changes before making any edits."
 
# Step 2: 범위 확인 후 피처 브랜치에서 auto-edit으로 실제 변경
git checkout -b feature/auth-jwt-refactor
codex --approval-mode auto-edit \
  "Convert the auth middleware to JWT. \
   Follow error handling rules in AGENTS.md. Do not modify existing test files."
 
# Step 3: diff 검토 후 테스트 자동 수정
# 반드시 격리 컨테이너 또는 throw-away 브랜치에서 실행
codex --full-auto \
  "Run npm test, fix failing test cases, and verify with another npm test run."

Step 1에서 에이전트가 변경 계획을 먼저 제시하도록 프롬프트를 구성하는 게 핵심입니다. 변경 범위가 예상보다 크거나 다르면 Step 2로 넘어가지 않는다는 기준을 팀이 사전에 합의해두면 좋습니다.

시나리오 2: 대규모 모노레포 마이그레이션

수백 개 파일에 걸친 마이그레이션은 범위를 논리적 단위로 잘게 쪼개는 것이 핵심입니다. "코드베이스를 개선해줘" 같은 넓은 지시 대신 서비스 단위로 태스크를 분리하면 결과가 훨씬 예측 가능합니다.

bash

# 전체 분석 먼저
codex --approval-mode suggest \
  "Identify candidates for microservice extraction from the legacy Express router. \
   Suggest a dependency graph and recommended extraction order."
 
# 서비스별로 별도 브랜치에서 순차 실행
git checkout -b migrate/user-service
codex --approval-mode auto-edit \
  "Extract user-related routes and business logic into a UserService class. \
   Modify the existing router to call UserService. Do not change other services."
 
# 검증은 격리 환경에서
# 반드시 격리 컨테이너 또는 throw-away 브랜치에서 실행
codex --full-auto \
  "Write unit tests for UserService and verify they pass with npm test."

시나리오 3: CI/CD 파이프라인에 테스트 자동 수정 루프 내장

full-auto는 격리 컨테이너 안에서 가장 효과적입니다. 테스트 실행 → 실패 분석 → 자동 수정 → 재실행 루프를 CI 단계에 내장하면 리팩토링 브랜치의 테스트 유지 비용을 크게 줄일 수 있습니다.

yaml

# .github/workflows/codex-test-fix.yml 예시
jobs:
  auto-fix-tests:
    runs-on: ubuntu-latest
    container:
      image: node:20-slim
    steps:
      - uses: actions/checkout@v4
      - name: Install Codex CLI
        run: npm install -g @openai/codex
      - name: Run tests and auto-fix failures
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex --full-auto \
            "Run npm test, analyze failures, and fix them. \
             Run npm test again to verify. \
             If tests still fail after 3 attempts, stop and summarize the root causes."

컨테이너 환경이라 별도의 네트워크 차단 샌드박스 없이도 격리가 보장됩니다. --dangerously-bypass-approvals-and-sandbox 플래그는 이처럼 컨테이너가 이미 격리를 보장하는 환경 전용이며, 로컬 워크스페이스에서는 사용하지 않는 것을 권장합니다.

멀티 에이전트 파이프라인으로 확장

단일 Codex CLI 인스턴스를 넘어서려면, Codex CLI를 MCP 서버로 노출해 Agents SDK로 오케스트레이션할 수 있습니다. 리팩토링 에이전트가 변경을 완료하면 별도 검증 에이전트가 결과를 리뷰하고 머지 여부를 판단하는 파이프라인입니다.

다이어그램 3

이 패턴의 실용적 가치는 리스크 분류 자동화에 있습니다. 변경 규모, 수정된 파일 유형, 테스트 커버리지 변동을 기준으로 검증 에이전트가 "자동 머지 가능", "사람 검토 필요", "재작업 요청" 중 하나를 판단하도록 구성할 수 있습니다. 초기 파이프라인 구성 비용이 있지만, 반복적인 리팩토링 작업이 많은 팀이라면 투자 대비 효과가 충분합니다.

장점과 단점

장점

항목	내용
점진적 자율성 제어	suggest → auto-edit → full-auto 3단계로 팀의 신뢰 수준에 맞춰 위임 범위 조절 가능
OS 수준 격리	별도 인프라 없이 Seatbelt / bubblewrap으로 강력한 격리 제공
AGENTS.md 표준화	팀 컨벤션을 에이전트가 매 태스크마다 자동 준수
MCP 확장성	멀티 에이전트 오케스트레이션, 기존 CI 툴체인 편입 가능
오픈소스	기업 보안 요구사항에 맞게 커스터마이징 가능

단점

항목	내용
full-auto의 파괴적 잠재성	미커밋 작업 덮어쓰기, 의도치 않은 셸 명령 실행 위험
프롬프트 인젝션 위험	악성 외부 데이터가 에이전트 동작을 오조종할 수 있음
대규모 diff 리뷰 부담	수천 라인 변경 시 사람이 전부 검토하기 어려움
API 비용	장시간 작업은 상당한 토큰 소비

실무에서 흔한 실수

로컬에서 full-auto 사용

격리 컨테이너 없이 로컬 워크스페이스에서 --full-auto를 쓰면 미커밋 변경이 덮어써질 수 있습니다. full-auto는 throw-away 컨테이너 또는 격리된 피처 브랜치에서만 사용하는 것이 원칙입니다.

태스크 범위를 너무 넓게 정의

"전체 코드베이스를 현대화해줘" 같은 지시는 결과가 예측 불가능합니다. "auth 미들웨어를 JWT로 변환해줘"처럼 범위를 좁게 정의할수록 에이전트의 출력이 안전하고 리뷰가 가능해집니다.

deny-read 설정 누락

.env, 자격 증명 파일에 대한 읽기 차단 없이 에이전트를 실행하면 프롬프트 인젝션 공격에 취약합니다. config.toml의 deny_read 설정은 선택이 아닙니다.

AGENTS.md 없이 시작

팀 컨벤션이 AGENTS.md에 정의되어 있지 않으면, 에이전트가 생성한 코드가 코드 리뷰에서 반복적으로 되돌아올 수 있습니다. 에이전트를 처음 도입하는 시점에 AGENTS.md 초안부터 만드는 것이 좋습니다.

시작하기

1단계: deny-read와 AGENTS.md 먼저 세팅하기

~/.codex/config.toml에 .env와 자격 증명 파일 경로를 deny-read로 추가하고, 프로젝트 루트에 AGENTS.md를 만들어 팀 코딩 표준을 정의합니다. 이 두 가지가 기본 안전망입니다.

2단계: 작은 태스크를 suggest 모드로 먼저 실행해보기

범위가 명확한 작은 리팩토링을 suggest 모드로 실행하면 에이전트가 어떤 변경 계획을 세우는지 파악할 수 있습니다. 계획이 예상과 맞을 때 다음 단계로 넘어가는 기준을 팀과 사전에 합의해두면 좋습니다.

3단계: 격리 브랜치에서 auto-edit → full-auto 순서로 전환해보기

신뢰할 수 있는 태스크에 한해 피처 브랜치를 만들고 auto-edit으로 올라간 다음, 테스트 수정 단계만 격리 컨테이너에서 full-auto로 실행합니다. 이 패턴이 팀에 익숙해지면 위임 범위를 점진적으로 넓혀갈 수 있습니다.

참고 자료

#Codex CLI#샌드박스#승인 정책#AGENTS.md#AI 에이전트#full-auto

Codex CLI의 샌드박스와 승인 정책은 두 개의 독립된 축이다 — 그 구조를 알면 대규모 리팩토링을 단계별로 위임할 수 있다 | DEV BAK - 기술블로그

Codex

Codex CLI의 샌드박스와 승인 정책은 두 개의 독립된 축이다 — 그 구조를 알면 대규모 리팩토링을 단계별로 위임할 수 있다

Codex CLI란

GitHub에서 수만 개의 스타를 받으며 활발하게 개발 중이고, 웹 기반 Codex 앱이 추가된 이후 사용자 기반이 빠르게 성장했습니다.

보안의 두 축: 샌드박스와 승인 정책

Codex CLI의 보안 구조는 하나의 레버가 아니라 두 개의 독립된 축으로 구성됩니다.

에이전트의 액션은 두 레이어를 순서대로 통과합니다. 샌드박스 레이어를 통과하지 못하면 승인 정책에 도달조차 하지 않습니다.

다이어그램 1

세 가지 모드는 두 축의 프리셋이다

모드	승인 정책	샌드박스	적합한 상황
`suggest`	모든 액션 승인 요청	기본 적용	태스크 탐색, 프로덕션 첫 적용
`auto-edit`	파일 수정 자동 / 셸 명령 승인	기본 적용	파일 변경은 신뢰하되 셸은 통제
`full-auto`	모든 액션 자동 실행	워크스페이스-쓰기	격리 컨테이너, CI 자동화 루프

Codex CLI에 전달하는 프롬프트는 영어로 작성하는 것이 결과 일관성 면에서 더 안정적입니다. 아래 코드 예시도 영어 프롬프트를 기준으로 작성했습니다.

bash

# 모드별 사용 예시
codex --approval-mode suggest "Review the auth module refactoring plan and list affected files"
codex --approval-mode auto-edit "Add error handling to all service layer functions"
 
# 반드시 격리 컨테이너 또는 throw-away 브랜치에서 실행
codex --full-auto "Run tests and fix any failures, then verify with another test run"

AGENTS.md: 팀 표준을 에이전트에 주입하기

markdown

# AGENTS.md 예시 (프로젝트 루트)
 
## 코딩 표준
- TypeScript strict 모드 유지
- 모든 async 함수에 try-catch 포함
- 테스트 파일은 __tests__/ 디렉터리에
 
## 금지 패턴
- console.log 직접 사용 금지 (logger 사용)
- any 타입 사용 금지
 
## 워크플로
- 변경 전 반드시 현재 테스트 커버리지 확인
- 변경 후 npm test 실행 필수

--print-instructions 플래그로 실제로 로드된 AGENTS.md 병합 내용을 확인할 수 있습니다. 설정이 제대로 주입되고 있는지 검증할 때 유용합니다.

파일시스템 보안: deny-read 정책

toml

# ~/.codex/config.toml
[sandbox]
deny_read = [
  ".env",
  ".env.*",
  "**/*.pem",
  "**/credentials.json",
  "~/.ssh/**"
]

실전 적용

시나리오 1: auth 미들웨어 리팩토링 — 3단계 점진적 위임

실무에서 가장 많이 쓰는 패턴은 suggest → auto-edit → full-auto 순서로 단계를 올려가는 방식입니다. 단계마다 결과를 확인하며 신뢰를 쌓아갑니다.

다이어그램 2

bash

# Step 1: suggest 모드로 리팩토링 범위 먼저 확인
codex --approval-mode suggest \
  "Refactor the auth middleware from session-based to JWT. \
   Show the list of affected files and the planned changes before making any edits."
 
# Step 2: 범위 확인 후 피처 브랜치에서 auto-edit으로 실제 변경
git checkout -b feature/auth-jwt-refactor
codex --approval-mode auto-edit \
  "Convert the auth middleware to JWT. \
   Follow error handling rules in AGENTS.md. Do not modify existing test files."
 
# Step 3: diff 검토 후 테스트 자동 수정
# 반드시 격리 컨테이너 또는 throw-away 브랜치에서 실행
codex --full-auto \
  "Run npm test, fix failing test cases, and verify with another npm test run."

시나리오 2: 대규모 모노레포 마이그레이션

bash

# 전체 분석 먼저
codex --approval-mode suggest \
  "Identify candidates for microservice extraction from the legacy Express router. \
   Suggest a dependency graph and recommended extraction order."
 
# 서비스별로 별도 브랜치에서 순차 실행
git checkout -b migrate/user-service
codex --approval-mode auto-edit \
  "Extract user-related routes and business logic into a UserService class. \
   Modify the existing router to call UserService. Do not change other services."
 
# 검증은 격리 환경에서
# 반드시 격리 컨테이너 또는 throw-away 브랜치에서 실행
codex --full-auto \
  "Write unit tests for UserService and verify they pass with npm test."

시나리오 3: CI/CD 파이프라인에 테스트 자동 수정 루프 내장

yaml

# .github/workflows/codex-test-fix.yml 예시
jobs:
  auto-fix-tests:
    runs-on: ubuntu-latest
    container:
      image: node:20-slim
    steps:
      - uses: actions/checkout@v4
      - name: Install Codex CLI
        run: npm install -g @openai/codex
      - name: Run tests and auto-fix failures
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex --full-auto \
            "Run npm test, analyze failures, and fix them. \
             Run npm test again to verify. \
             If tests still fail after 3 attempts, stop and summarize the root causes."

멀티 에이전트 파이프라인으로 확장

다이어그램 3

장점과 단점

장점

항목	내용
점진적 자율성 제어	suggest → auto-edit → full-auto 3단계로 팀의 신뢰 수준에 맞춰 위임 범위 조절 가능
OS 수준 격리	별도 인프라 없이 Seatbelt / bubblewrap으로 강력한 격리 제공
AGENTS.md 표준화	팀 컨벤션을 에이전트가 매 태스크마다 자동 준수
MCP 확장성	멀티 에이전트 오케스트레이션, 기존 CI 툴체인 편입 가능
오픈소스	기업 보안 요구사항에 맞게 커스터마이징 가능

단점

항목	내용
full-auto의 파괴적 잠재성	미커밋 작업 덮어쓰기, 의도치 않은 셸 명령 실행 위험
프롬프트 인젝션 위험	악성 외부 데이터가 에이전트 동작을 오조종할 수 있음
대규모 diff 리뷰 부담	수천 라인 변경 시 사람이 전부 검토하기 어려움
API 비용	장시간 작업은 상당한 토큰 소비

실무에서 흔한 실수

로컬에서 full-auto 사용

태스크 범위를 너무 넓게 정의

deny-read 설정 누락

AGENTS.md 없이 시작

시작하기

1단계: deny-read와 AGENTS.md 먼저 세팅하기

2단계: 작은 태스크를 suggest 모드로 먼저 실행해보기

3단계: 격리 브랜치에서 auto-edit → full-auto 순서로 전환해보기

참고 자료

#Codex CLI#샌드박스#승인 정책#AGENTS.md#AI 에이전트#full-auto

Codex CLI란

보안의 두 축: 샌드박스와 승인 정책

세 가지 모드는 두 축의 프리셋이다

AGENTS.md: 팀 표준을 에이전트에 주입하기

파일시스템 보안: deny-read 정책

실전 적용

시나리오 1: auth 미들웨어 리팩토링 — 3단계 점진적 위임

시나리오 2: 대규모 모노레포 마이그레이션

시나리오 3: CI/CD 파이프라인에 테스트 자동 수정 루프 내장

멀티 에이전트 파이프라인으로 확장

장점과 단점

실무에서 흔한 실수

시작하기

참고 자료

Codex CLI란

보안의 두 축: 샌드박스와 승인 정책

세 가지 모드는 두 축의 프리셋이다

AGENTS.md: 팀 표준을 에이전트에 주입하기

파일시스템 보안: deny-read 정책

실전 적용

시나리오 1: auth 미들웨어 리팩토링 — 3단계 점진적 위임

시나리오 2: 대규모 모노레포 마이그레이션

시나리오 3: CI/CD 파이프라인에 테스트 자동 수정 루프 내장

멀티 에이전트 파이프라인으로 확장

장점과 단점

실무에서 흔한 실수

시작하기

참고 자료

추천 포스트

GitHub 이슈에서 PR까지 — Codex Cloud Agent로 팀 백로그를 비동기 병렬 처리로 전환하기

프론트엔드 개발자를 위한 OpenAI Codex 2025 실전 가이드 — 터미널 하나로 PR까지