Codex CLI란 무엇이고, 샌드박스 권한 설정이 왜 중요한가요?

Codex CLI는 내 컴퓨터의 프로젝트 파일을 읽고, 수정하고, 명령을 실행할 수 있는 OpenAI의 터미널 기반 AI 코딩 도구입니다. 샌드박스는 이 도구가 접근할 수 있는 파일과 네트워크의 범위를 제한하는 안전장치입니다. 처음 사용할 때 중요한 것은 권한을 무조건 풀어주는 것이 아니라, 작업에 필요한 범위만 허용하는 것입니다.

“코드를 고쳐 달라고 했는데 왜 수정하지 못하지?”, “허용 버튼을 눌러도 내 파일은 안전할까?” 처음 사용하는 분들이 부딪히는 질문을 중심으로 개념과 설정 방법을 정리했습니다.

최종 내용 확인: 2026년 9월 17일 · OpenAI 공식 문서 기준. 설치된 CLI 버전과 운영체제, 조직 정책에 따라 화면과 동작은 달라질 수 있습니다. 이 글은 공식 문서를 바탕으로 한 안내이며 특정 버전의 실행 테스트 결과는 아닙니다.

Codex CLI란? ChatGPT에 코드를 물어보는 것과 무엇이 다른가요?

핵심 차이는 코드에 관해 답을 받는 데서 끝나지 않고, 허용한 작업 공간에서 실제 파일 수정과 명령 실행까지 이어갈 수 있다는 점입니다. CLI는 Command Line Interface의 약자로, 터미널에 글자로 명령을 입력하는 방식을 뜻합니다.

일반적인 ChatGPT 채팅에서 코드 조언을 받고 직접 복사해 적용하는 방식과 달리, Codex CLI에서는 “이 페이지를 모바일에서도 잘 보이게 수정해줘”라고 요청하고 프로젝트 파일의 변경 결과를 확인할 수 있습니다. 다만 ChatGPT에도 여러 실행 도구와 연동 기능이 있으므로, 모든 ChatGPT 사용 방식이 단순한 질의응답에 한정된다는 뜻은 아닙니다.

• 프로젝트 구조와 기존 코드 설명
• HTML·CSS 수정, 기능 추가, 오류 원인 분석
• 허용 범위 안에서 테스트 등 로컬 명령 실행
• 변경한 내용 요약과 검토 지원

공식 안내: OpenAI Codex CLI

샌드박스 권한이란? 별도의 가상 폴더에서 작업하나요?

샌드박스는 단순한 가상 폴더나 자동 백업 공간이 아니라, Codex가 실행하는 명령의 접근 범위를 제한하는 보안 장치입니다. 운영체제의 보안 기능을 이용해 파일 변경과 네트워크 사용 등의 경계를 정합니다.

중요한 점은 허용된 프로젝트 안에서는 실제 파일이 변경될 수 있다는 것입니다. “샌드박스 안이니 원본은 그대로겠지”라고 생각하면 안 됩니다. 프로젝트 안에서 실행하는 Git, 패키지 설치 도구, 테스트 명령도 이러한 경계의 영향을 받습니다.

샌드박스와 승인 정책은 다릅니다

• 샌드박스: 어디까지 접근하고 무엇을 변경할 수 있는가?
• 승인 정책: 어떤 상황에서 멈추고 사용자에게 허용 여부를 물을 것인가?

예를 들어 프로젝트 안의 파일 수정은 허용하되, 범위를 벗어나거나 네트워크를 사용해야 할 때에는 승인을 요청하도록 구성할 수 있습니다. 승인 질문을 줄이는 것과 접근 제한을 없애는 것은 같은 설정이 아닙니다.

근거: OpenAI 샌드박스 및 권한 안내

초보자는 어떤 권한을 선택하면 되나요?

설명과 검토만 필요하면 읽기 전용으로, 실제 파일 수정이 필요하면 작업 공간 안의 쓰기를 허용하는 방식으로 시작하세요. 문제가 생겼다는 이유만으로 전체 접근 권한을 주는 것은 권하지 않습니다.

하고 싶은 작업	샌드박스 모드	알아둘 점
코드 읽기·구조 설명·수정 계획 검토	read-only	파일 쓰기가 제한됩니다. 실제 수정에는 별도 허용이 필요할 수 있습니다.
프로젝트 파일 수정·새 파일 생성·로컬 테스트	workspace-write	작업 공간 내 쓰기를 허용합니다. 경계 밖 작업은 별도 승인이나 설정이 필요합니다.
샌드박스 제한 없이 실행	danger-full-access	파일·네트워크의 샌드박스 경계를 제거합니다. 초보자의 일반 작업에는 권하지 않습니다.

일반적인 로컬 수정 작업의 출발점으로는 workspace-write와 on-request 승인 정책 조합을 권합니다. 다만 이 설정도 프로젝트 안의 모든 변경이 올바르다는 것을 보장하지는 않습니다.

Codex CLI 설치와 샌드박스 권한 설정 방법

1. 설치하고 작업할 폴더에서 시작합니다

Node.js와 npm이 준비된 환경에서는 다음 명령으로 설치할 수 있습니다. 터미널에서 실행하는 명령입니다.

npm i -g @openai/codex

작업할 프로젝트 폴더로 이동한 뒤 아래처럼 실행하고, 처음이라면 화면 안내에 따라 인증합니다. 사용자 홈 전체보다 수정할 프로젝트 폴더를 작업 위치로 잡는 것이 좋습니다.

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

--sandbox workspace-write는 작업 공간 내 쓰기를, --ask-for-approval on-request는 필요할 때 승인을 요청하는 정책을 지정합니다.

2. 실행 중인 Codex 대화창에서 상태를 확인합니다

아래 명령은 일반 터미널 셸이 아니라 Codex가 실행된 대화 입력창에 입력합니다.

/status

현재 세션 설정과 승인 정책, 쓰기가 허용된 경로 등을 확인합니다. 내가 수정하려는 파일이 허용 범위에 있는지부터 살펴보세요.

3. 필요할 때만 권한을 조정합니다

/permissions

권한 메뉴에서 작업 목적에 맞는 항목을 선택하고, 다시 /status로 상태를 확인합니다. 메뉴 이름과 선택 가능한 항목은 버전이나 조직 설정에 따라 다를 수 있습니다.

기존 안내 정정: 이 글의 이전 버전에 있던 codex sandbox status, codex sandbox mode workspace-write 대신, 현재 공식 문서에 안내된 위의 슬래시 명령과 시작 옵션을 사용하도록 수정했습니다.

공식 참조: 대화창 슬래시 명령 · CLI 실행 옵션

Codex가 파일을 수정하지 못하면 무엇부터 확인하나요?

읽기 전용 설정인지, 대상 파일이 작업 범위 안에 있는지, 운영체제나 조직 정책이 막고 있는지를 순서대로 확인하세요. 모든 오류를 샌드박스 문제라고 생각하고 전체 권한을 주면 원인은 그대로인데 위험만 커질 수 있습니다.

1. 현재 설정 확인: /status에서 승인 정책과 쓰기 허용 경로를 확인합니다.
2. 대상 경로 확인: 수정할 파일이 현재 프로젝트 밖에 있거나 다른 위치를 가리키고 있지 않은지 확인합니다.
3. 오류 종류 구분: 파일 쓰기 거부인지, 네트워크 차단인지, 인증 실패인지 실제 메시지를 읽습니다. 네트워크가 막힌 상황에서 파일 쓰기 권한만 바꿔도 해결되지 않습니다.
4. 최소 범위만 조정: 필요한 폴더나 작업만 허용합니다. 회사·학교의 관리 정책은 관리자 확인이 필요할 수 있습니다.
5. 변경 확인: 다시 시도한 뒤 실제 파일 차이와 실행 결과를 확인합니다.

예시: “index.html을 수정해줘”라고 했는데 거부되는 경우

다음은 이해를 돕기 위한 가상 상황입니다. 프로젝트 파일이 읽기 전용 경계 때문에 수정되지 않는다면, 먼저 /status로 확인하고 /permissions에서 프로젝트 수정에 필요한 권한을 선택합니다. 이후 해당 파일만 수정하도록 다시 요청합니다. 작업 폴더 밖의 파일이나 운영체제 권한 문제라면 이 절차만으로 해결되지 않을 수 있습니다.

처음 사용할 때 자주 묻는 질문

권한을 허용하면 내 파일이 삭제될 수도 있나요?

허용 범위 안에서는 파일이 수정되거나 삭제될 수 있습니다. 샌드박스는 접근 범위를 제한하는 장치이지, 변경 내용의 정확성을 보장하거나 원본을 자동 복구하는 백업 기능이 아닙니다. 중요한 프로젝트는 시작 전에 별도 복사본을 만들거나 Git으로 현재 상태를 저장하세요. Git을 사용하더라도 추적하지 않은 파일이나 저장하지 않은 변경까지 모두 복구되는 것은 아닙니다.

승인 요청이 자꾸 뜨는데 매번 허용해도 되나요?

요청한 명령, 대상 경로, 외부 연결 여부를 확인한 뒤 필요한 작업만 허용하세요. 승인 창이 반복되는 것은 작업이 현재 허용 범위를 벗어나기 때문일 수 있습니다. 일회성 승인이면 충분한 일을 세션 전체나 전체 접근으로 넓히지 않는 편이 좋습니다. 특히 파일 삭제, 외부 전송, 배포처럼 되돌리기 어려운 작업은 따로 검토하세요.

workspace-write면 컴퓨터 전체가 안전한가요?

샌드박스 밖의 영향을 제한하는 데 도움이 되지만, “어떤 작업을 해도 안전하다”는 뜻은 아닙니다. 프로젝트 안의 실제 파일은 바뀔 수 있고, 별도로 승인한 작업은 범위가 더 넓어질 수 있습니다. 비밀번호·API 키·고객정보가 담긴 파일을 불필요하게 작업 대상으로 넣지 말고, 민감한 자료가 없는 작업용 복사본을 사용하는 것이 좋습니다.

코딩을 전혀 몰라도 사용할 수 있나요?

자연어로 요청할 수 있지만, 결과 확인까지 없어지는 것은 아닙니다. 처음에는 화면 문구 수정, 간격·색상 조정, 코드 설명처럼 작은 작업부터 시작하세요. 결제·로그인·개인정보 처리·운영 데이터베이스 변경은 오류의 영향이 크므로 충분한 테스트와 전문가 검토가 필요합니다.

수정한 내용이 마음에 들지 않으면 되돌릴 수 있나요?

미리 저장한 복사본이나 Git 이력이 있어야 안정적으로 되돌릴 수 있습니다. “원래대로 해줘”라는 요청만 믿기보다 변경 전 상태를 확보하고, 한 번에 작은 단위로 수정하세요. 자동 복구를 전제로 운영 중인 원본에 바로 작업하는 것은 피하는 편이 좋습니다.

처음이라면 이 순서로 시작하세요

1. 민감한 정보가 없는 작은 프로젝트나 복사본을 준비합니다.
2. 먼저 파일 구조와 수정 계획을 설명하게 합니다.
3. 실제 수정이 필요할 때 작업 공간 내 쓰기를 허용합니다.
4. 한 번에 한 가지를 요청하고, 변경된 파일과 차이를 확인합니다.
5. 테스트한 뒤 적용하거나 배포합니다.

처음 요청은 이렇게 구체적으로 적으면 좋습니다.

이 프로젝트의 구조를 먼저 설명해줘. 아직 파일은 수정하지 마. 모바일 화면을 개선하려면 어떤 파일을 바꿔야 하는지와 예상 영향을 알려줘.

계획을 확인한 뒤에는 “설명한 파일만 수정하고, 변경 내용과 확인해야 할 테스트 항목을 알려줘”처럼 범위를 좁혀 이어가면 됩니다. 다만 자연어 지시는 기술적인 권한 제한을 대신하지 않으므로 설정도 함께 확인하세요.

마무리: 권한을 많이 주는 것보다 범위를 잘 정하는 것이 중요합니다

Codex CLI는 코드를 설명하는 도구를 넘어 실제 프로젝트에 손을 대는 도구입니다. 그래서 작업 폴더 확인 → 필요한 권한만 허용 → 변경 검토 → 테스트 순서를 습관으로 만드는 것이 중요합니다.

초보자라면 “막히면 전체 권한 허용”이 아니라 “무엇이 왜 막혔는지 확인”하는 쪽으로 접근하세요. 그 습관이 AI 코딩을 더 안전하게 활용하는 출발점입니다.