Codex 권한과 승인 설정 이해하기: 작업 범위를 작게 시작하는 법

요약: Codex 권한은 접근할 수 있는 파일·네트워크의 경계와, 그 경계를 넘어갈 때의 승인 방식을 나눠 이해하면 쉽습니다. 먼저 작업 폴더와 결과를 정하고 읽기, 수정, 설치에 필요한 범위를 고르세요. 승인 질문이 줄었다고 접근 범위가 좁아지는 것도, 넓은 권한을 주었다고 코드 품질이 좋아지는 것도 아닙니다.

1. 세 가지 설정을 구분해서 읽기

OpenAI 공식 Sandbox 문서에서 샌드박스는 명령의 파일·네트워크 접근 경계이고, 승인 정책은 추가 승인을 요청할 시점을 정합니다. 승인 검토자는 그 요청을 사용자 또는 자동 검토자 중 누가 판단하는지를 정합니다. 자동 검토를 선택해도 기존 샌드박스 경계가 저절로 넓어지지는 않습니다.

실무에서는 “어디에 접근할 수 있나”, “막힌 행동을 요청할 수 있나”, “누가 판단하나”라는 세 질문으로 읽어 보세요. 예를 들어 프로젝트 안의 문장을 고치는 일은 현재 경계 안에서 가능할 수 있지만, 다른 저장소의 자료를 가져오거나 의존성을 내려받는 일은 별도의 접근이 필요할 수 있습니다. 실제 가능 여부는 현재 적용된 설정으로 확인해야 합니다.

프롬프트의 “이 폴더만 수정”은 작업 지시입니다. 기술적인 파일 차단과 같은 의미는 아닙니다. 반대로 읽기 전용 설정으로 실행하면서 “파일을 바로 고쳐 달라”고 쓰면 지시만으로 쓰기 권한이 생기지 않습니다. 작업 범위를 말로 정하고, 실제 권한 설정이 그 범위에 맞는지 확인하는 두 단계가 필요합니다.

2. 할 일에 맞춰 작업 범위를 고르는 표

아래 표는 작성자가 구성한 선택 기준입니다. 모든 환경의 기본값을 설명하는 표가 아니라, 이번 작업에 어떤 접근이 필요한지 판단할 때 사용할 수 있는 안내입니다. 시작할 때는 결과물을 하나로 좁히고, 작업 중 드러난 필요에 따라 범위를 조정하세요.

원하는 결과	우선 필요한 범위	추가 접근을 판단할 때
코드 구조와 오류 원인 설명	관련 소스와 설정 읽기	없는 파일을 읽었다고 가정하지 않는지 확인
검색 입력 오류 수정	프로젝트의 관련 파일 쓰기와 로컬 검증	테스트가 만드는 캐시·결과 파일의 위치 확인
새 패키지 설치	설치 대상 파일 수정과 필요한 네트워크	대상 패키지, 다운로드 출처, 설치 스크립트 확인
다른 저장소의 공통 모듈 비교	그 저장소의 필요한 파일 읽기	두 저장소 전체에 쓰기 권한이 필요한지 구분
외부 서비스에 결과 게시	서비스 연결과 해당 쓰기 작업	초안 작성과 실제 게시의 대상·권한을 구분

프로젝트 폴더를 선택할 때는 소스, 설정, 필요한 테스트가 들어 있는 가장 가까운 공통 폴더를 기준으로 삼으세요. 문서 폴더 전체나 여러 고객 프로젝트를 함께 열면 관련 없는 자료까지 작업 맥락에 들어갈 수 있습니다. 공통 모듈이 밖에 있다면 필요한 파일을 읽게 할지, 별도의 프로젝트로 다룰지부터 결정하면 됩니다.

읽기 전용 조사에도 결과 저장 경로를 정해야 합니다. “검토만 해 달라”면서 로컬 보고서 파일 생성을 요구하면 쓰기가 필요합니다. 화면에 설명을 받는 것과 파일로 보고서를 만드는 것을 구분해 요청하면 설정을 잘못 고르는 일을 줄일 수 있습니다.

3. 앱·CLI에서 실제 설정 확인하기

공식 권한 모드 문서는 일반적인 작업에 Ask for approval부터 시작하도록 안내합니다. 이 모드는 작업 영역 안의 읽기·수정과 일반 로컬 명령을 허용하며 경계를 넘는 작업은 요청합니다. 데스크톱 앱과 IDE는 입력창 아래 권한 메뉴, CLI는 /permissions를 사용합니다. CLI의 /status로 작업 영역도 확인할 수 있습니다.

데스크톱 앱에서 추가 모드가 보이지 않는다면 현재 문서의 Settings > General > Permissions를 확인하세요. 모드를 메뉴에 표시하도록 켜는 것과 현재 대화에서 선택하는 것은 다릅니다. 조직 정책으로 선택이 제한될 수도 있습니다. 메뉴 이름을 찾았다는 이유만으로 기존 대화의 권한이 바뀌었다고 판단하지 마세요.

CLI에서 의도를 명시해 시작하려면 아래와 같은 공식 지원 옵션을 사용할 수 있습니다. 첫 줄은 읽기 중심 조사, 둘째 줄은 프로젝트 수정에 쓰는 예입니다. 두 줄을 연속 실행하는 절차가 아니라 자신의 작업에 맞는 한 줄을 선택하는 예시입니다.

codex --sandbox read-only --ask-for-approval on-request
codex --sandbox workspace-write --ask-for-approval on-request

공식 승인·보안 문서는 이러한 조합과 보호 경로를 설명합니다. workspace-write라고 해도 .git, .agents, .codex 같은 경로에는 별도의 보호가 있습니다. 따라서 작업 폴더 안이라는 이유만으로 모든 설정 파일의 쓰기가 허용된다고 가정하면 안 됩니다.

설정 파일을 쓸 때 헷갈리는 지점

기존 샌드박스 방식의 프로젝트 수정 기본값을 표현하는 작은 예시는 다음과 같습니다. 실제 설정 파일 전체를 이 내용으로 덮어쓰라는 뜻은 아닙니다. 기존 설정과 조직 요구사항을 확인하고 적용할 항목만 판단하세요.

sandbox_mode = "workspace-write"
approval_policy = "on-request"
approvals_reviewer = "user"

현재 권한 프로필 문서에는 베타 방식인 default_permissions와 [permissions]도 있습니다. 이 방식과 기존 sandbox_mode 방식은 함께 합쳐 적용되는 설정이 아니므로 서로 다른 예제를 섞지 마세요. 새 프로필을 쓰려면 해당 문서의 호환 조건부터 확인하는 편이 좋습니다.

Windows에서도 네이티브 샌드박스와 권한 프로필을 지원합니다. 오류가 났다는 이유만으로 WSL이 반드시 필요하다고 단정하지 말고, 실행 중인 환경과 적용된 정책부터 확인하세요. 같은 PC라도 네이티브 Windows 작업과 WSL 안의 작업은 경로와 설치된 도구가 다를 수 있습니다.

4. 복사해서 바꿔 쓸 사전 확인 프롬프트

다음 예시는 작성자가 구성한 가상 검색 앱 작업입니다. 대괄호를 자신의 경로와 요구사항으로 바꾸세요. 처음에는 자료를 읽고 필요한 접근을 설명받아 작업 준비 상태를 파악하는 데 사용할 수 있습니다.

작업 목표: [검색어 앞뒤 공백 때문에 검색이 실패하는 원인 설명]
대상 프로젝트: [실제 프로젝트 경로]
조사 범위: [검색 입력 컴포넌트, 호출 함수, 관련 테스트]
현재 작업 폴더와 확인 가능한 권한 설정을 알려 주세요.
먼저 관련 파일을 읽고 원인 후보와 근거 위치를 정리해 주세요.
이 단계의 결과는 대화에 작성해 주세요.
추가 접근이 필요하면 대상 경로·서비스, 목적, 예상 변경을 설명해 주세요.
확인하지 못한 설정이나 자료는 미확인이라고 표시해 주세요.

이 요청으로 얻을 것은 “모든 권한이 안전하다”는 선언이 아니라 필요한 파일과 검증 방법의 목록입니다. 검색 컴포넌트를 읽고도 원인을 못 찾았다면 실제 오류 메시지나 요청 데이터가 더 필요할 수 있습니다. 그때는 개인정보를 제거한 재현 입력을 제공하면 넓은 파일 접근 없이도 조사에 도움이 됩니다.

작업을 실행할 때는 원하는 동작과 완료 기준을 함께 추가하세요. 다음 문장은 범위 지시의 예시이며 앱의 권한 설정을 변경하지 않습니다.

수정 목표: [검색어 앞뒤 공백만 제거하고 기존 검색 동작 유지]
수정 대상: [확인한 파일과 관련 테스트]
기존 API 요청 형식과 다른 화면의 동작을 유지해 주세요.
프로젝트에 이미 설치된 도구로 관련 검증을 진행해 주세요.
추가 설치가 필요하면 패키지·출처·파일 변경·설치 스크립트를 설명해 주세요.
최종 결과에 수정 파일, 실행한 명령, 결과, 미실행 검증을 적어 주세요.

5. 승인 요청을 읽는 다섯 가지 질문

승인 화면에서는 명령 이름만 보지 말고 입력과 결과가 어디로 가는지 읽으세요. “의존성 설치”라는 목적은 같아도 프로젝트 안에 파일을 생성하는 설치와 전역 도구 설치는 변경 위치가 다릅니다. 내려받는 자료가 단순 데이터인지 실행할 스크립트인지도 판단에 도움이 됩니다.

1. 대상: 어느 폴더, 호스트, 저장소 또는 서비스에 접근하는가?
2. 입력: 어떤 파일이나 값을 읽거나 전송하는가?
3. 변경: 무엇을 새로 만들고, 고치고, 삭제하는가?
4. 필요성: 지금 요구를 해결하는 데 왜 이 행동이 필요한가?
5. 범위: 한 번, 이번 작업, 세션 중 어떤 범위로 허용하는가?

설명이 부족하면 “이 명령의 파일 변경, 외부 통신, 설치 후 실행될 코드와 더 작은 대안을 설명해 달라”고 요청해 보세요. 승인 화면이 제시하는 범위 중 작업을 끝내기에 충분한 범위를 선택하면 됩니다. 반복적으로 같은 요청이 나온다면 무조건 넓게 허용하기보다 승인 대상이 매번 달라지는지 확인하세요.

자동 검토도 판단을 틀릴 수 있습니다. 승인됨은 그 행동이 검토를 통과했다는 의미이며, 실행 성공이나 결과 정확성을 보장하지 않습니다. 승인된 설치가 실패했다면 그다음에는 설치 로그와 파일 상태를 읽어야 합니다. 같은 명령을 다시 요청하는 것만으로 원인이 해결되지는 않습니다.

6. 막혔을 때 원인을 구분하는 표

보이는 증상	먼저 확인할 것	다음 조치
파일을 찾지 못함	오타, 상대 경로 기준, 실제 파일 존재	정확한 경로를 확인하고 읽을 파일 지정
접근 거부	읽기·쓰기 구분, 작업 경계, OS 권한	실패한 대상과 필요한 접근만 다시 판단
설치 다운로드 실패	차단 메시지, DNS·프록시·저장소 응답	네트워크 정책과 서비스 오류를 구분
테스트 명령 실패	실행 파일 존재, 의존성, 실제 테스트 오류	도구 준비 문제와 코드 실패를 따로 기록
권한 모드 선택 불가	조직 요구사항과 현재 설정	허용된 범위에서 가능한 작업부터 진행

예를 들어 테스트가 임시 파일을 쓰려다 실패했다면 소스 수정 권한만으로 충분하지 않을 수 있습니다. 필요한 쓰기 위치를 확인하고 프로젝트 안의 결과 경로를 사용할 수 있는지 검토하세요. 반대로 테스트가 예상값 불일치로 실패했다면 권한을 넓혀도 해결되지 않습니다. 실패 메시지의 어느 부분이 접근 제한을 뜻하는지부터 구분해야 합니다.

approval_policy = "never"는 승인 질문을 하지 않는다는 뜻이며 샌드박스를 해제하는 뜻이 아닙니다. 경계 밖 행동이 실패할 수 있으므로 자동 실행이 필요할 때도 필요한 접근과 실패 보고를 설계해야 합니다. Full access는 광범위한 파일 변경과 네트워크 실행을 가능하게 하므로 오류 해결의 기본 선택으로 삼지 마세요.

7. 작업 뒤에는 권한보다 결과를 검증하기

수정이 끝났다면 요청한 파일과 실제 변경 파일이 맞는지 먼저 비교하세요. 예상 밖의 잠금 파일, 설정 파일, 생성 파일이 있다면 왜 바뀌었는지 확인합니다. 기존에 사용자가 편집하던 변경과 이번 작업의 변경도 구분해야 합니다. 변경 목록이 작아도 핵심 동작을 검사하지 않았다면 완료 근거는 부족할 수 있습니다.

• 문제 입력과 정상 입력을 각각 확인했는가?
• 보고된 명령은 실제 실행되었고 결과가 남아 있는가?
• 실패한 검증과 실행하지 못한 검증이 따로 표시되었는가?
• 외부 게시나 설치를 했다면 대상과 결과가 요청에 맞는가?
• 추가 접근을 임시로 허용했다면 적용 범위가 끝났는가?

가상 검색 앱이라면 공백이 있는 “ 금속 ”, 공백이 없는 “금속”, 공백만 있는 입력으로 기대 동작을 정의할 수 있습니다. 수정 파일과 검증 결과를 함께 보면 접근이 허용되었는지와 요구가 해결되었는지를 혼동하지 않게 됩니다. 이 글의 예시는 설명용으로 구성했으며 해당 프로젝트를 실행하거나 테스트한 사례가 아닙니다.

8. 처음 시작할 때의 실용적인 순서

프로젝트 폴더를 확인하고, 읽기 또는 수정 목적을 정한 다음 현재 권한을 확인하세요. 필요한 행동이 경계를 넘을 때 대상과 목적을 읽고 추가 범위를 판단합니다. 마지막에는 변경 파일과 검증 결과를 확인하세요. 이 순서를 익히면 권한 메뉴에서 가장 넓은 항목을 고르는 대신, 이번 작업에 필요한 접근을 설명할 수 있게 됩니다.

공식 출처 및 확인일: 권한 모드, Sandbox, 승인·보안, 권한 프로필. 2026년 10월 3일 확인. 설정 예시는 현재 환경과 조직 정책에 맞게 조정하세요.