Codex CLI에서 –sandbox read-only를 써야 하는 때

파일을 건드리기 전에 상태부터 보게 할 때

--sandbox read-only는 Codex에게 “일단 읽고 판단만 해라”라고 묶어두고 싶을 때 쓴다. 처음부터 수정까지 맡기기 애매한 저장소, 남이 만진 브랜치, 인증 상태가 헷갈리는 환경에서는 이게 꽤 도움이 된다. Codex가 못 한 건지, 내가 잘못된 폴더에서 돌린 건지, 아니면 실행 권한 때문에 막힌 건지 먼저 갈라낼 수 있다.

내 경우에는 새 프로젝트를 열자마자 바로 “고쳐줘”를 던지면 결과가 지저분해질 때가 있었다. Codex가 코드를 읽기도 전에 테스트를 돌리다 캐시를 만들고, 패키지 매니저가 뭔가를 쓰려고 하고, 그러다 실패 로그가 섞인다. 그러면 정작 봐야 할 구조는 안 보이고 샌드박스 실패만 먼저 보게 된다.

읽기 전용으로 시작하면 기대치를 낮출 수 있다. 이 모드에서는 저장소를 훑고, 파일을 읽고, 원인을 추적하는 쪽에 잘 맞는다. 실제 파일 수정은 못 한다고 보면 된다.

read-only가 잘 맞는 작업

처음 보는 코드베이스에서는 read-only가 꽤 편하다. “어디를 고쳐야 할지”가 아직 안 보일 때는 수정 권한이 오히려 빠른 길이 아니다. 먼저 지도를 그리게 하는 쪽이 낫다.

상황	read-only가 맞는 이유
새 저장소 구조를 파악할 때	Codex가 파일을 읽고 흐름을 설명하는 데 집중한다
버그 원인을 먼저 나눠 보고 싶을 때	수정 없이 로그, 호출 흐름, 설정을 볼 수 있다
남이 작업 중인 브랜치일 때	실수로 파일을 건드릴 가능성을 줄인다
리뷰나 설계 검토를 맡길 때	“바꾸기”보다 “읽고 판단하기”가 목적이다
인증이나 폴더 상태가 애매할 때	Codex 문제인지 환경 문제인지 먼저 분리할 수 있다

처음엔 이걸 너무 보수적인 설정이라고 생각했다. 그런데 실제로는 반대였다. 읽기 전용으로 한 번 훑고 나면, 수정 모드로 넘어갔을 때 작업 지시가 훨씬 짧아진다.

옵션이 어디 붙는지 먼저 확인한다

대화형 Codex CLI에서 샌드박스 옵션은 codex 쪽에 붙는다. 실제 작업을 바로 맡기기 전에, 도움말에서 옵션이 인식되는지부터 볼 수 있다.

codex --sandbox read-only --help

--sandbox 값에 read-only, workspace-write, danger-full-access가 보이면 일단 CLI가 이 옵션을 알고 있는 상태다. 여기서 --help는 작업 실행이 아니라 확인용이다. 실제로는 --help 자리에 작업 지시를 붙이거나, 그냥 대화형 세션으로 들어가서 이어가면 된다.

한 번에 끝나는 작업을 codex exec로 던질 때도 같은 식으로 확인할 수 있다.

codex exec --sandbox read-only --help

codex exec는 비대화형으로 한 번 실행하고 끝내는 쪽에 가깝다. 여러 번 주고받으며 좁혀야 하는 작업이면 대화형 세션이 편하고, “이 저장소 구조만 읽고 요약해줘”처럼 한 번에 끝나는 일은 exec가 더 가볍다.

답답해지는 순간도 있다

read-only는 읽기 전용이라서 답답한 순간이 분명히 있다. Codex가 원인을 찾았는데 바로 고치지는 못한다. 테스트를 돌리는 중에도 도구가 캐시나 임시 파일을 쓰려고 하면 막힐 수 있다.

작업	read-only에서 생길 수 있는 일
파일 수정	실패한다
포맷터 실행	쓰기 모드면 바꾸려 하므로 막힐 수 있다
패키지 설치	node_modules, lockfile, 캐시 때문에 막힐 수 있다
일부 테스트 실행	스냅샷, 캐시, 임시 파일 생성에서 막힐 수 있다
빌드	출력 디렉터리를 만들려다 실패할 수 있다

여기서 헷갈리면 Codex가 틀린 줄 알기 쉽다. 그런데 실제로는 그냥 샌드박스가 막은 것일 때가 있다. 그래서 read-only로 시작한 세션에서는 “왜 못 고쳤지?”보다 “읽기 전용에서 여기까지 봤구나”라고 읽는 게 맞다.

수정까지 맡길 준비가 됐으면 그때 workspace-write로 넘어가는 게 자연스럽다. 처음부터 danger-full-access로 가는 건 거의 필요하지 않았다. 적어도 평소 블로그나 코드 저장소 정리 작업에서는 그렇다.

로그인 문제와 샌드박스 문제를 섞지 않는다

Codex CLI는 일반 사용 흐름에서는 ChatGPT 로그인, 그러니까 OAuth 기반 로그인을 기본으로 두는 게 제일 덜 헷갈린다. API key는 별도 OpenAI API 호출을 하거나, CLI와 API 인증을 비교하는 글에서나 다루면 된다. 설치하고 로그인하는 글에서 API key 명령부터 꺼내면 처음 보는 사람 입장에서는 길이 두 개로 갈라진다.

상태가 이상하면 먼저 로그인 상태만 본다.

codex login status

내 환경에서는 이 명령이 Logged in using ChatGPT처럼 현재 로그인 방식을 알려줬다. 여기서 이미 로그인되어 있다면, 다음에는 폴더와 샌드박스를 봐야 한다. 로그인부터 다시 하려고 들면 문제를 더 섞을 수 있다.

예를 들어 Codex가 파일을 못 고친다. 이때 가능한 원인은 적어도 세 가지다.

• 로그인 상태가 풀렸다
• 작업 폴더가 내가 생각한 저장소가 아니다
• --sandbox read-only라서 쓰기가 막혔다

이 셋을 한꺼번에 의심하면 오래 걸린다. codex login status로 인증을 먼저 빼고, 현재 폴더를 보고, 마지막에 샌드박스 모드를 보면 훨씬 덜 꼬인다.

내가 쓰는 기준

처음부터 고칠 파일이 분명하면 read-only로 오래 끌 필요는 없다. 예를 들어 “이 함수 하나 타입 에러 고쳐줘”처럼 범위가 좁고, 저장소 상태도 괜찮다면 workspace-write가 낫다.

반대로 질문이 이런 모양이면 read-only로 시작한다.

• “이 에러가 어디서 나는지 봐줘”
• “이 프로젝트 구조 설명해줘”
• “수정하지 말고 원인만 찾아줘”
• “어떤 파일을 건드려야 할지 먼저 알려줘”
• “이 브랜치에서 위험한 변경이 있는지 봐줘”

내 경우에는 특히 “수정하지 말고”라는 말을 붙일 때 read-only를 같이 쓴다. 말로만 막는 것보다 실행 권한까지 막아두는 편이 마음이 편하다.