--add-dir 는 Codex CLI의 주 작업 폴더 옆에 추가 쓰기 가능 디렉터리를 허용하는 실행 옵션입니다. -C 는 세션의 주 작업 폴더를 정합니다. --add-dir 는 두 번째 폴더를 추가합니다. 공식 CLI 레퍼런스는 이 옵션을 여러 번 반복해 경로를 더 넣을 수 있다고 설명합니다.

다만 옵션을 알아보는 것과 실제 쓰기 권한이 적용되는 것은 다른 문제입니다. 이 글에서 확인한 codex-cli 0.144.6 은 유효 권한이 추가 쓰기 루트를 허용하지 않으면 --add-dir 를 무시하고 시작을 중단했습니다. --sandbox workspace-write 를 명시한 비민감 시험에서는 추가 폴더에 정확히 파일 하나만 만들 수 있었습니다. 이 결과는 현재 설치 환경의 관찰값이므로, 독자는 자신의 codex --help 와 시작 로그를 기준으로 판단해야 합니다.

• -C , --add-dir , --sandbox workspace-write 의 역할 차이
• 현재 설치된 Codex CLI에서 옵션을 먼저 찾는 방법
• 비민감 시험 폴더 두 개로 추가 쓰기 범위를 확인하는 6단계
• 넓은 경로와 자격증명 폴더를 피해야 하는 이유
• 여러 추가 폴더를 넣을 때 지켜야 할 검토 순서

OpenAI 공식 CLI 레퍼런스는 --add-dir PATH 를 주 작업공간과 함께 추가 디렉터리의 쓰기 접근을 허용하는 옵션으로 정의합니다. 같은 옵션을 반복하면 경로를 여러 개 지정할 수 있습니다. 반면 --cd, -C PATH 는 Codex가 요청 처리를 시작하기 전에 주 작업 디렉터리를 정합니다.

두 옵션은 목적이 다릅니다. -C 는 세션의 출발점을 고릅니다. --add-dir 는 출발점을 바꾸지 않고 별도 경로를 추가 쓰기 경계에 넣습니다. --sandbox 는 모델이 만든 셸 명령에 적용할 샌드박스 정책을 read-only , workspace-write , danger-full-access 가운데 고르는 별도 옵션입니다.

애플리케이션 저장소와 그 저장소가 참조하는 문서 폴더처럼 정확히 두 경로를 한 작업에서 수정해야 할 때 이 옵션이 필요합니다. 파일을 읽어 요약하기만 하거나 한 저장소 안에서 끝나는 작업이라면 쓰기 경계를 넓힐 이유가 없습니다.

공식 문서는 이 옵션을 Codex CLI의 경로 기반 전역 플래그로 설명합니다. ChatGPT 웹 설정이나 Codex 대화창의 슬래시 명령이 아닙니다. 최소 버전, 요금제, 지역, 언어, 운영체제별 제공 조건은 해당 레퍼런스에서 확인되지 않습니다. 따라서 실행 전에 현재 설치본의 도움말을 확인해야 합니다.

목표: 검토한 추가 폴더에 probe.txt 파일 하나를 만들고, 내용이 줄바꿈 없이 정확히 add-dir-ok인지 확인한다.

허용 입력: 사람이 확인한 주 작업 폴더 절대 경로, 추가 폴더 절대 경로, 두 시험 폴더의 현재 파일 목록만 사용한다.

제외 입력: 홈 디렉터리 전체, 자격증명 폴더, 실제 저장소, 고객 자료, 비밀값, 다른 경로의 파일은 읽거나 수정하지 않는다.

출력 형식: 1) 주 작업 폴더 2) 추가 폴더 3) 만들 파일의 전체 경로 4) 실행할 작업 5) 검증 결과 6) 변경된 파일 전체 목록 순서로 보고한다.

완료 기준: 추가 폴더에 probe.txt 한 개만 존재하고 내용은 줄바꿈 없이 정확히 add-dir-ok여야 한다. 주 폴더와 다른 경로에는 변경이 없어야 한다.

추정 금지: 경로, 기존 파일, 권한, 샌드박스 상태, 승인 여부를 추정하지 않는다. 확인할 수 없으면 확인 필요로 표시하고 실행을 멈춘다.

승인 지점: 파일을 만들기 전에 대상 전체 경로와 정확한 내용을 보여 주고 사람의 승인을 기다린다. 이름 변경, 이동, 덮어쓰기, 삭제, 외부 전송, 실제 저장소 수정은 실행하지 않는다.

프롬프트는 샌드박스 설정을 대신하지 않습니다. 시작 명령의 경로와 권한이 먼저 맞아야 하며, Codex가 제시한 작업도 승인 전에 다시 확인해야 합니다.

추가 폴더는 하나부터 시작하세요. 공식 레퍼런스는 여러 경로가 필요하면 --add-dir 를 반복하라고 안내합니다. 쉼표로 경로를 합치거나 넓은 상위 폴더 하나로 대체하지 않습니다.

codex -C "/absolute/path/main" \
--sandbox workspace-write \
--add-dir "/absolute/path/docs" \
--add-dir "/absolute/path/shared-types"

각 추가 경로마다 필요한 이유, 허용할 파일, 금지할 변경을 따로 적습니다. 경로를 하나 더 넣을 때마다 같은 probe 검증을 반복하세요. 예상 밖 변경이 없을 때만 다음 경로를 검토합니다.

주 작업 폴더는 명령 실행과 작업 맥락의 기준이 됩니다. 테스트를 주로 실행할 저장소를 -C 에 둡니다. 꼭 함께 수정해야 하는 좁은 경로만 --add-dir 로 추가하면 검토 순서가 분명해집니다.

• --add-dir 는 편의 옵션이 아니라 쓰기 경계를 넓히는 옵션입니다. 홈 디렉터리나 드라이브 루트를 통째로 넣지 않습니다.
• workspace-write 가 설정돼도 Codex의 판단과 생성 결과가 정확하다는 뜻은 아닙니다. 변경 파일과 내용을 사람이 확인합니다.
• -C , --add-dir , --sandbox 는 서로 다른 역할을 합니다. 추가 경로를 넣었다고 주 작업 폴더가 바뀌지는 않습니다.
• 이 글의 오류와 probe 결과는 codex-cli 0.144.6 , WSL 환경의 관찰값입니다. 최소 지원 버전이나 다른 운영체제의 동일 동작을 의미하지 않습니다.
• Ignoring --add-dir 오류가 보이면 경로가 허용됐다고 보고하지 않습니다. 현재 도움말과 조직 정책을 확인하세요. 우회 권한으로 넓히지 않습니다.
• danger-full-access , --yolo , 광범위한 상위 경로는 이 첫 실행 흐름에서 사용하지 않습니다.
• 실제 저장소를 연결하기 전에는 백업과 버전 관리 상태를 확인합니다. 삭제·이동·덮어쓰기는 별도 승인 뒤에 둡니다.

--add-dir 를 여러 번 사용할 수 있나요?

네. OpenAI 공식 CLI 레퍼런스는 여러 경로가 필요하면 --add-dir 를 반복하라고 설명합니다. 처음에는 경로 하나만 검증하세요. 각 경로를 추가할 때 쓰기 필요성과 민감 파일 여부를 다시 확인하는 편이 안전합니다.

-C 와 --add-dir 는 무엇이 다른가요?

-C 는 Codex가 요청 처리를 시작할 주 작업 디렉터리를 정합니다. --add-dir 는 그 주 작업공간 옆에 별도 디렉터리의 쓰기 접근을 추가합니다. 두 번째 경로를 주 폴더로 바꾸려는 목적이라면 --add-dir 가 아니라 -C 에 넣어야 합니다.

왜 Ignoring --add-dir 오류가 나오나요?

이 글의 codex-cli 0.144.6 에서는 유효 권한이 추가 쓰기 루트를 허용하지 않을 때 이 오류와 함께 시작이 중단됐습니다. --sandbox workspace-write 를 명시한 전용 시험은 통과했습니다. 다만 공식 레퍼런스는 이 오류를 모든 버전에 대한 진단 규칙으로 설명하지 않으므로, 현재 codex --help , 실행 정책, 시작 로그를 함께 확인해야 합니다.

추가 폴더가 허용되면 요청한 파일만 바뀌나요?

아닙니다. --add-dir 는 지정 경로를 쓰기 경계에 더하는 기능이지, 변경 대상을 파일 하나로 자동 제한하는 기능은 아닙니다. 프롬프트에서 대상 파일과 금지 작업을 좁힙니다. 실행 전 승인과 실행 후 변경 목록 검토도 별도로 해야 합니다.

• OpenAI Codex CLI command reference