Codex 프로필 설정 방법: --profile로 검토용 설정을 처음 불러오는 법
TL;DR
Codex 프로필은 작업마다 바꿔 쓰는 설정을 별도 파일에 보관하고
--profile
로 불러오는 기능입니다. 검토용 파일은 기본 위치에서
~/.codex/review.config.toml
로 만들고
codex --profile review
로 시작합니다.
프로필은 편리한 설정 계층이지 강제 보안 경계가 아닙니다. 프로젝트의
.codex/config.toml
과 실행할 때 붙인 CLI 옵션이 프로필보다 우선할 수 있으므로 실제 적용값까지 확인해야 합니다.
핵심 3줄 요약
codex --help
에서
--profile
을 확인하고 기존
~/.codex/config.toml
은 덮어쓰지 않습니다.~/.codex/review.config.toml
에 최상위 키로 읽기 전용 검토값만 적습니다.codex --profile review
로 시작한 뒤 비민감 테스트와 설정 우선순위를 확인합니다.이 글에서 다룰 내용
Codex 프로필의 한 문장 정의, 기본 설정과 프로필 파일의 차이, 검토용 프로필을 만드는 6단계, 복사해 쓸 검토 프롬프트, 우선순위와 버전 주의점, FAQ를 다룹니다.
Codex 프로필은 무엇이고 언제 쓰면 좋은가
Codex 프로필은 이름을 붙여 저장한 설정 계층을 CLI에서 선택해 불러오는 기능입니다. OpenAI 공식 Advanced Config 문서는
--profile profile-name
을 전달하면 Codex가 기본 사용자 설정을 읽은 다음
~/.codex/profile-name.config.toml
을 겹쳐 적용한다고 설명합니다.
기본값은 그대로 두고 코드 읽기, 깊은 검토, 제한된 실험처럼 목적이 다른 세션을 반복해서 열 때 유용합니다. 이번 예시는 파일을 수정하지 않는 첫 코드 검토를 목표로
review
프로필을 만듭니다.
인용한 공식 문서에는 모든 이용자에게 공통으로 적용되는 최소 버전이나 플랜 조건이 따로 없습니다. 계정, 지역, 언어, 기기, 가격 조건도 확인되지 않으므로 현재 설치본의 도움말에서
--profile
인식 여부를 먼저 봅니다.
시작 전에 파일 위치와 우선순위를 구분합니다
기본 사용자 설정은
~/.codex/config.toml
입니다.
review
라는 프로필은 같은 폴더의 별도 파일인
~/.codex/review.config.toml
에 둡니다. 프로필 이름에는 영문자, 숫자, 하이픈, 밑줄을 쓸 수 있습니다.
Codex 0.134.0 이상에서는 예전 방식인
[profiles.review]
테이블과 최상위
profile = "review"
선택자를 더 이상 읽지 않습니다. 프로필 파일 안에는
[profiles.review]
를 만들지 말고
sandbox_mode
같은 설정 키를 최상위에 적습니다.
설정 우선순위도 중요합니다. 공식 Config basics가 밝힌 순서는 높은 쪽부터 CLI 플래그와
--config
, 프로젝트
.codex/config.toml
, 선택한 프로필 파일, 기본 사용자
config.toml
, 시스템 설정, 내장 기본값입니다.
review.config.toml
에
read-only
를 적어도 모든 프로젝트에서 강제되지는 않습니다. 신뢰한 프로젝트의
.codex/config.toml
이 더 높은 계층에서 다른 값을 지정할 수 있습니다. 조직 관리 기기라면
requirements.toml
의 제한도 별도로 적용될 수 있습니다.
검토용 Codex 프로필을 처음 만드는 순서
1. 현재 설치본에서 --profile을 확인합니다
운영체제 셸에서 다음 명령을 실행합니다.
codex --version
codex --help
도움말의 공통 옵션에서
--profile
또는
-p
를 찾습니다.
$CODEX_HOME/<name>.config.toml
을 기본 사용자 설정 위에 겹친다는 설명도 확인합니다. 현재 설치본이 플래그를 인식하지 않으면 파일을 추정 작성하지 않고 공식 설치·업데이트 안내를 따로 확인합니다.
2. 기본 사용자 설정은 읽고 보존합니다
~/.codex/config.toml
이 있다면 현재 모델, 승인 정책, 샌드박스 설정을 먼저 확인합니다. 기존 파일을 지우거나 프로필 예시로 덮어쓰지 않습니다.
프로필은 기본 설정 위에 다른 값만 겹치는 파일입니다. 검토 세션에 필요한 차이만 기록하면 나중에 기본 설정이 바뀌어도 중복 관리가 줄어듭니다.
3. review.config.toml을 별도 파일로 만듭니다
~/.codex/review.config.toml
에 다음 내용을 저장합니다.
approval_policy = "on-request"
sandbox_mode = "read-only"
approval_policy = "on-request"
는 추가 권한이 필요한 행동을 Codex가 사용자에게 요청하도록 합니다.
sandbox_mode = "read-only"
는 샌드박스에서 파일 쓰기를 허용하지 않는 검토용 값입니다.
모델명과 reasoning effort는 이번 첫 설정에서 고정하지 않습니다. 계정과 조직 정책, 현재 모델 지원 범위를 확인하지 않은 채 복사하면 프로필 로드와 모델 선택 문제를 한꺼번에 만들 수 있기 때문입니다.
4. 프로젝트 밖의 비민감 테스트 폴더에서 먼저 엽니다
처음부터 고객 저장소나 운영 코드에서 시험하지 않습니다. 민감한 파일과 프로젝트
.codex/config.toml
이 없는 임시 폴더로 이동한 뒤 다음 명령을 운영체제 셸에 입력합니다.
codex --profile review
--profile
은 Codex 대화형 composer 안에 입력하는 slash command가 아닙니다. 새 Codex 세션을 시작할 때 운영체제 셸에 전달하는 전역 CLI 옵션입니다.
5. 비민감 요청으로 첫 검토를 실행합니다
테스트 폴더에서 아래 프롬프트를 입력합니다. 실제 소스 코드나 자격증명은 넣지 않습니다.
현재 폴더를 수정하지 말고 파일 목록과 읽기 전용 검토 계획만 보여주세요.
파일 생성, 이름 변경, 삭제, 외부 전송은 하지 마세요.
완료 기준은 응답을 받고 테스트 전후 파일 상태가 같음을 사람이 확인하는 것입니다. 모델 답변이 “수정하지 않았다”고 말하는 것만으로 완료 처리하지 않습니다.
6. 필요할 때만 실험적 디버그 출력으로 교차 확인합니다
현재 공식 CLI 레퍼런스는
codex debug prompt-input
을 Experimental로 표시합니다. 설치본이 이 명령을 제공할 때만 아래처럼 비민감 문자열로 모델에 보이는 입력 목록을 JSON으로 출력할 수 있습니다.
codex --profile review debug prompt-input "프로필 로드 확인용 비민감 테스트"
출력의 permissions instructions에서 실제
sandbox_mode
가
read-only
인지 확인합니다. 작성 시점의 로컬
codex-cli 0.144.6
에서는 모델 요청 없이 작동했습니다. 다만 Experimental 기능이므로 모든 버전의 필수 단계로 취급하지 않습니다.
실제 프로젝트에서 적용값을 다시 확인하는 법
테스트가 끝났다면 대상 저장소의
.codex/config.toml
유무와 값을 읽습니다. 프로젝트 설정은 프로필보다 우선하므로 같은
codex --profile review
명령도 저장소에 따라 최종 샌드박스가 달라질 수 있습니다.
한 번만 더 강한 제한이 필요하면 해당 실행의 전용 CLI 플래그를 검토할 수 있습니다. 다만 이 글의 완료 기준은 프로필을 만들고 불러오는 것이며 조직 정책 변경이나 공유 설정 배포까지 포함하지 않습니다.
프로필 파일을 팀에 공유할 때는 모델 접근 권한, 조직 요구사항, 프로젝트 설정을 따로 검토합니다. 파일 이름이 같다고 팀원 모두에게 같은 최종 권한이 보장되는 것은 아닙니다.
그대로 복사해 쓸 읽기 전용 검토 프롬프트
목표: 현재 작업 폴더의 파일을 변경하지 않고 검토 범위와 확인할 위험만 정리한다.
허용 입력: 현재 폴더의 비민감 소스 파일, 사람이 선택한 설정 파일, 테스트 결과, 공개 문서.
제외 입력: API 키, access token, 비밀번호, 원문 인증 파일, 고객 데이터, 운영 비밀, 승인되지 않은 상위 폴더와 외부 경로.
출력 형식: 파일 또는 범위 | 관찰 근거 | 확인할 위험 | 다음 검토 | 사람 승인 필요 여부의 5개 열로 작성한다.
완료 기준: 파일 생성·수정·이름 변경·삭제·외부 전송 없이 검토 계획과 근거가 정리된 상태다.
추정 금지: 읽지 않은 파일의 내용, 숨은 조직 정책, 모델·플랜 제공 조건, 취약점 존재, 테스트 성공을 만들어 내지 않는다.
승인 지점: 파일 변경, 명령 실행, 네트워크 사용, 추가 경로 접근, 결과 공유는 담당자가 범위와 되돌리기 방법을 확인한 뒤 승인한다.
이 프롬프트는 프로필의 권한을 대체하지 않습니다. 실제 적용된 설정과 파일 상태를 별도로 확인해야 합니다.
실전 활용 팁
프로필에는 기본 설정과 다른 값만 남기는 편이 관리하기 쉽습니다.
review.config.toml
에 모델명, 공급자, MCP 서버, 샌드박스 값을 모두 복사하면 어떤 계층이 최종값을 만들었는지 추적하기 어려워집니다.
검토가 끝난 뒤 구현으로 넘어갈 때는 같은 세션에서 권한을 넓히기보다 목적이 분명한 별도 세션을 여는 편이 낫습니다. 검토 결과와 실제 변경 기록을 구분할 수 있기 때문입니다.
주의할 점
-
--profile은 운영체제 셸에서 Codex를 시작할 때 쓰는 옵션입니다. 대화형 composer에 보낼 프롬프트가 아닙니다. - 최신 문서 기준 프로필은 별도
profile-name.config.toml파일이며[profiles.name]테이블을 쓰지 않습니다. - 프로젝트
.codex/config.toml과 CLI 플래그가 프로필보다 높은 우선순위를 가집니다. -
read-only프로필은 편리한 기본값이지 독립된 보안 경계나 조직 정책이 아닙니다. -
codex debug prompt-input은 Experimental이므로 도움말에서 인식할 때만 비민감 테스트에 씁니다. - 자격증명, 고객 자료, 운영 저장소는 첫 프로필 검증 범위에서 제외합니다.
- 파일 변경과 권한 확대는 결과와 되돌리기 방법을 검토한 뒤 따로 승인합니다.
자주 묻는 질문
review 프로필은 config.toml 안에 만들면 되나요?
Codex 0.134.0 이상에서는 아닙니다.
~/.codex/review.config.toml
이라는 별도 파일을 만들고 설정 키를 최상위에 적습니다. 예전
[profiles.review]
방식은 현재 문서에서 지원되지 않는 이전 형식입니다.
--profile은 어디에 입력하나요?
운영체제의 터미널 셸에서
codex --profile review
처럼 실행합니다. 이미 열린 Codex 대화형 composer에 입력하는 slash command가 아닙니다.
read-only를 적으면 파일 변경이 완전히 막히나요?
프로필만으로 그렇게 단정할 수 없습니다. 프로젝트 설정과 CLI 옵션이 프로필보다 우선합니다. 대상 저장소의
.codex/config.toml
, 조직의 관리 정책, 실제 적용값을 함께 확인해야 합니다.
프로필마다 모델을 지정해야 하나요?
필수는 아닙니다. 프로필은 기본 사용자 설정 위에 다른 값만 겹칩니다. 모델을 지정하지 않으면 더 낮은 계층의 값을 이어받을 수 있으며 프로젝트 설정이나 CLI 옵션이 다시 덮을 수 있습니다.
출처
마무리
Codex 프로필의 첫 설정은 기본
config.toml
을 고치는 일이 아닙니다.
review.config.toml
을 별도로 만들고
codex --profile review
로 불러오는 작업입니다.
처음에는 비민감 테스트 폴더와 읽기 전용 값으로 시작합니다. 실제 저장소에 적용하기 전에는 프로필보다 우선하는 프로젝트 설정과 CLI 옵션도 확인합니다. 이 순서를 지키면 검토 편의와 권한 확인을 함께 챙길 수 있습니다.
