Codex -C –add-dir 차이, 여러 폴더를 함께 쓸 때

메타디스크립션: Codex -C –add-dir 차이와 여러 폴더 명령을 설명합니다. -C는 주 작업 폴더를 정하고 --add-dir는 추가 쓰기 경로를 엽니다.

Codex -C –add-dir의 차이는 간단합니다. -C는 주 작업 루트를 정하고, --add-dir는 그 주 작업 루트를 유지한 채 추가로 쓸 수 있는 폴더를 더합니다. 앱 코드가 있는 폴더를 주 프로젝트로 삼고 별도 문서 폴더도 고쳐야 한다면, 앱 폴더는 -C, 문서 폴더는 --add-dir로 지정하면 됩니다.

codex -C "/경로/app" --add-dir "/경로/docs"

둘을 같은 옵션처럼 바꾸어 쓰면 안 됩니다. --add-dir를 붙여도 현재 작업 디렉터리와 주 프로젝트가 보조 폴더로 바뀌지는 않습니다.

먼저 주 프로젝트를 -C로 고릅니다

OpenAI 공식 Projects 문서는 Codex CLI가 시작한 디렉터리를 해당 대화의 프로젝트로 취급하며, 다른 폴더를 주 프로젝트로 삼으려면 --cd <directory> 또는 짧은 형태인 -C를 쓰라고 안내합니다.

터미널에서 현재 위치를 옮기지 않고 앱 폴더를 기준으로 시작하려면 다음처럼 입력합니다.

codex -C "/경로/app"

이 폴더는 단순한 첫 검색 위치가 아닙니다. 현재 공식 문서는 primary folder가 Git 작업과 AGENTS.md, skills, config.toml 자동 발견의 기본이라고 설명합니다. 어느 저장소의 지침과 Git 상태를 기준으로 일할지 먼저 정하는 옵션으로 보는 편이 안전합니다.

관련 폴더를 더 써야 할 때만 --add-dir를 붙입니다

앱 저장소 바깥의 문서 폴더도 같은 작업에서 수정해야 한다면 보조 경로를 추가합니다.

codex -C "/경로/app" \
  --add-dir "/경로/docs"

추가 폴더가 둘 이상이면 --add-dir를 폴더마다 반복합니다.

codex -C "/경로/app" \
  --add-dir "/경로/docs" \
  --add-dir "/경로/shared"

현재 Codex CLI 0.155.1의 도움말은 --add-dir를 “primary workspace 옆에서 쓸 수 있는 추가 디렉터리”로 설명합니다. 즉 보조 폴더를 새 주 프로젝트로 만드는 옵션이 아니라, 쓰기 가능한 범위를 명시적으로 하나 더 여는 옵션입니다.

실제로 --add-dir 유무를 대조했습니다

2026년 9월 23일 macOS의 Codex CLI 0.155.1에서 workspace-write, approval never로 비민감 폴더 두 개를 사용했습니다. 주 작업 루트는 같게 두고, 주 폴더 밖의 보조 경로에 파일을 쓰게 했습니다.

--add-dir가 없을 때는 쓰기가 writing outside of the project로 차단됐습니다. 같은 실행 조건에서 보조 경로를 --add-dir로 추가하자 해당 경로가 writable roots에 나타났고, 요청한 7바이트 ALLOWED 파일이 만들어졌습니다. 실행 중 pwd는 계속 주 작업 루트를 가리켰습니다.

이 결과는 두 옵션의 역할을 한 문장으로 보여 줍니다.

• -C: 명령과 프로젝트 탐색의 기준이 되는 주 작업 루트
• --add-dir: 주 작업 루트 밖에서 추가로 쓸 수 있게 허용한 경로

보조 폴더의 지침까지 자동으로 읽는다고 가정하지 마세요

쓰기가 가능해졌다는 사실과 프로젝트 지침을 자동 발견한다는 사실은 다릅니다. 공식 문서는 secondary folder를 파일 검색·읽기·편집에 쓸 수 있다고 하면서도, AGENTS.md, skills, config.toml 자동 발견의 기본은 primary folder라고 구분합니다.

보조 폴더에 별도 규칙이 있다면 “추가했으니 알아서 읽었겠지”라고 넘기지 마세요. 중요한 규칙은 주 프로젝트의 지침에서 연결하고, 새 세션에서 실제 활성 지침과 대상 경로를 확인하는 편이 안전합니다.

어떤 지침 파일이 실제로 활성인지 모호하다면 Codex가 어떤 AGENTS.md를 읽었는지 확인하는 순서로 전역 파일과 프로젝트 경로를 먼저 구분하세요. CODEX_HOME과 프로젝트 루트를 같은 위치로 잡아 지침이 겹친다면 Codex HOME과 프로젝트 AGENTS.md가 중복될 때의 표식 대조를 함께 볼 수 있습니다.

여러 폴더 작업 전 확인할 세 가지

1. Git 작업과 지침의 기준이 될 폴더 하나를 -C로 정합니다.
2. 같은 결과에 꼭 필요한 보조 폴더만 --add-dir로 추가합니다.
3. 첫 작업 전에 pwd와 대상 파일 경로를 출력해 주 작업 루트와 보조 쓰기 경로를 구분합니다.

폴더를 많이 추가할수록 편한 것이 아니라 수정 가능한 범위가 넓어집니다. 서로 무관한 저장소라면 한 세션에 모두 열기보다 작업을 나누는 편이 결과 검토도 쉽습니다.

확인 범위

이 글의 쓰기 대조는 macOS와 Codex CLI 0.155.1에서 한 번 재현한 결과입니다. 다른 OS나 이후 버전에서는 먼저 codex --help로 현재 옵션을 확인하세요. 공식 근거는 2026년 9월 23일 확인한 OpenAI Projects and chats입니다. 정확 월간 검색량은 확인하지 못했으며, Google 관련 검색어와 공개 질문은 실제 필요가 있다는 정성 신호로만 사용했습니다.

자주 묻는 질문

-C를 두 번 쓰면 두 폴더가 모두 열리나요?

그렇게 사용하지 않습니다. 주 작업 폴더 하나는 -C로 정하고, 나머지 폴더는 각각 --add-dir로 추가합니다.

--add-dir를 붙이면 현재 폴더도 바뀌나요?

바뀌지 않습니다. 직접 대조에서 pwd는 -C로 정한 주 작업 루트를 계속 가리켰고, 추가 폴더만 쓰기 가능한 경로에 들어왔습니다.

폴더를 읽기만 할 때도 추가해야 하나요?

이 글에서 직접 확인한 범위는 workspace-write의 외부 쓰기입니다. 읽기 범위는 현재 sandbox와 실행 환경에 따라 다를 수 있으므로 codex --help와 실제 파일 읽기 결과를 별도로 확인하세요.

검증 기준

• 마지막 업데이트일: 2026-09-23
• 확인 환경: macOS, Codex CLI 0.155.1, workspace-write, approval never
• 주요 근거: OpenAI Projects and chats, 공개 다중 디렉터리 질문
• 직접 확인: 같은 주 작업 루트에서 --add-dir 없음은 외부 쓰기 차단, 있음은 7바이트 파일 생성 성공
• 한계: Windows·Linux와 이후 CLI 버전의 동작은 독립 재현하지 않았다.