Codex CLI 설치 후 가장 먼저 확인할 설정들

설치가 끝이 아니었다

Codex CLI를 설치하고 바로 작업을 던져보면, 생각보다 먼저 막히는 지점은 모델 성능이 아니다.

지금 어떤 계정으로 붙어 있는지
기본 모델/승인/샌드박스가 어떻게 잡혀 있는지
지금 어느 폴더를 작업 루트로 보고 있는지

이 세 가지가 애매한 채로 일을 시키면, 결과가 이상해도 원인을 갈라내기 어렵다. Codex가 못 한 건지, 내가 홈 디렉터리에서 돌린 건지, 로그인이 풀려 있었던 건지부터 나눠 봐야 한다.

설정값을 어떻게 튜닝할지 다루는 글은 아니다. 값을 건드리기 전에 상태부터 확인하는 순서를 정리해 둔다. 인증은 ChatGPT 로그인(OAuth)을 기준으로 삼았다. API key 방식은 설치 직후에 밟는 길이 아니라 여기서는 빼 두었고, 공식 문서는 글 맨 끝에 모아 두었다.

한 장으로 보는 점검 순서

CLI가 실행되는지
ChatGPT 로그인 세션인지
지금 폴더가 의도한 프로젝트인지
config.toml의 핵심 키만 읽기
필요하면 codex doctor로 한 번 더 훑기

1. 버전과 로그인부터

먼저 CLI 자체가 PATH에 잡혔는지, 로그인 세션이 살아 있는지 본다.

codex --version
codex login status

문제가 없다면 대략 이런 출력이 나온다.

codex-cli 0.144.5
Logged in using ChatGPT

Logged in using ChatGPT가 보이면 이 글이 기준으로 삼은 OAuth 방식으로 붙은 상태다. 브라우저에서 ChatGPT 계정으로 로그인해 두면, CLI가 그 세션을 그대로 가져다 쓴다.

로그인이 안 되어 있으면 codex login으로 ChatGPT 로그인을 마친 뒤 codex login status를 다시 보면 된다. API key 로그인(codex login --with-api-key)은 설치 직후 상태를 확인하는 단계에서 쓰는 방식이 아니다. 직접 API를 호출하거나 키 기반 자동화를 붙일 때만 따로 꺼내 보면 된다.

2. 지금 어느 폴더에서 돌리는지

Codex는 현재 작업 디렉터리를 기준으로 프로젝트를 읽는다. 터미널 탭을 여러 개 쓰다 보면, “블로그 저장소에서 실행 중”이라고 생각해도 실제로는 홈이나 다른 프로젝트일 때가 있다.

pwd

Git 저장소 안이라면 루트도 같이 확인한다.

git rev-parse --show-toplevel

정상일 때는 pwd 결과와 같은 저장소 경로, 또는 그 하위 경로에서 바라본 저장소 루트가 나온다. Git 저장소 밖이면 git rev-parse는 실패하는 게 정상이다. 그 경우에는 프로젝트 폴더로 이동한 뒤 다시 보거나, 실행 시 작업 루트를 명시한다.

작업 루트를 명시하고 싶을 때는 -C / --cd를 쓴다. 아래는 “지금 git 저장소 루트를 작업 루트로 두고 CLI가 뜨는지” 확인하는 예시다.

codex -C "$(git rev-parse --show-toplevel)" --version

자주 쓰는 저장소라면 ~/.codex/config.toml에 프로젝트 구간이 생기는 경우도 있다. 형태만 보면 경로 문자열 아래에 trust_level 같은 값이 붙는다. 이 값 하나가 만능 보안 스위치는 아니다. 다만 Codex가 그 경로를 어떤 신뢰 수준으로 다루는지 확인하는 단서는 된다.

3. config.toml은 통째로 덤프하지 말고 핵심만

설정 파일 위치는 보통 홈 아래다.

macOS/Linux: ~/.codex/config.toml
~는 홈 디렉터리 (예: /Users/yourname)

파일이 아직 없을 수도 있다. 설치와 로그인만 한 직후라면 기본값으로 돌아가는 경우도 있어서, 없는 것 자체가 오류는 아니다.

test -f ~/.codex/config.toml && echo "config.toml 있음" || echo "config.toml 없음"

파일이 있더라도 전체를 블로그나 채팅에 그대로 붙이지 않는 편이 안전하다. 토큰 원문이야 아니겠지만 모델 설정, MCP, 로컬 경로처럼 개인 운영 정보가 섞이기 쉽다. 설치 직후에 볼 키는 아래 정도면 충분하다.

rg -n '^(model|approval_policy|sandbox_mode)\s*=' ~/.codex/config.toml

rg가 없다면 같은 목적으로 grep도 된다.

grep -nE '^(model|approval_policy|sandbox_mode)[[:space:]]*=' ~/.codex/config.toml

예시로 보일 수 있는 형태는 이렇다. 값은 환경마다 다르다.

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

각 키가 무엇을 가리키는지만 짧게 정리하면 이렇다.

키	무엇을 보나	설치 직후 기준
`model`	기본 모델	의도한 모델 이름인지
`approval_policy`	실행 전 승인 빈도	`untrusted` / `on-request` / `never`. 처음엔 자주 묻는 쪽이 안전
`sandbox_mode`	파일·네트워크 범위	`read-only` → `workspace-write` → `danger-full-access` 순으로 권한이 커짐

나는 모델 이름보다 sandbox와 approval 쪽을 먼저 본다. 모델이 얼마나 똑똑한지보다, 내가 허용한 범위 안에서만 움직이는지가 설치 직후의 사고를 막는 데는 훨씬 직접적이다. 값을 어떻게 조합하는지는 공식 approvals/security 문서에 자세히 나와 있다.

4. 한 번에 훑고 싶으면 doctor

원인을 갈라내는 데는 명령을 하나씩 나눠 보는 쪽이 낫다. 그래도 “지금 이 머신 상태가 대체로 괜찮은지”를 한 번에 보고 싶을 때가 있는데, 그럴 때 doctor를 쓴다.

codex doctor --summary

요약 화면에는 auth, config load, sandbox/approval, network 같은 항목이 줄줄이 나온다. 경고가 하나 떴다고 해서 당장 작업을 못 하는 건 아니다. 다만 설치 직후의 기준선을 남겨 두기에는 편하다. 더 자세한 출력이 필요하면 --summary를 빼고 실행한다.

codex doctor

doctor가 문제를 대신 고쳐 주지는 않는다. 빨간 항목이 보이면 다시 login, config, 작업 디렉터리 순서로 돌아가 원인을 나누면 된다.

설치 직후 복사해서 쓰는 최소 체크

프로젝트 폴더로 이동한 뒤 아래만 순서대로 실행해도, 초반에 헤매는 상황은 대부분 원인이 갈린다.

codex --version
codex login status
pwd
codex doctor --summary
test -f ~/.codex/config.toml && echo "config.toml 있음" || echo "config.toml 없음"

Git 저장소 안에서 작업 중일 때만 루트 확인을 추가한다.

git rev-parse --show-toplevel

config가 있을 때만 핵심 키를 읽는다.

rg -n '^(model|approval_policy|sandbox_mode)\s*=' ~/.codex/config.toml

여기까지 보면 다음 네 가지는 빠르게 갈린다.

인증 문제인지
엉뚱한 폴더인지
설정 파일이 없거나 값이 의도와 다른지
doctor가 가리키는 환경/연결 문제인지

다음에 보면 좋은 것

상태 확인이 끝나야 설정을 바꾸는 일도 의미가 생긴다. 다음 순서로는 보통 이런 주제가 온다.

sandbox_mode=read-only를 언제 쓰면 좋은지
로그인 상태가 자주 헷갈릴 때 볼 것
codex exec를 써도 되는 작업 / 아닌 작업

설치 직후에는 기능을 더 얹기보다 계정과 폴더, 승인·샌드박스 상태를 먼저 고정해 두는 쪽이 결국 시간을 아꼈다.