7. Settings에서 조정할 수 있는 것

Settings를 왜 먼저 설정해야 하나요?

Settings 열기

Settings 카테고리 한눈에 보기

각 카테고리 상세 설명

General (일반 설정)

• 1 "파일 오픈 위치"란?
  Codex가 코드 파일을 열 때 어디에서 열지를 정하는 설정입니다. 예를 들어, VS Code에서 열지, Codex 내장 에디터에서 열지를 선택할 수 있습니다. 이미 VS Code를 쓰고 있다면 "VS Code에서 열기"로 설정하면, Codex에서 파일을 클릭했을 때 바로 VS Code로 전환되어 편리합니다.
• 2 "명령 출력량"이란?
  Codex가 작업할 때 화면에 보여주는 작업 로그(기록)의 양입니다. "적음(Quiet)"으로 설정하면 화면이 깔끔하지만, Codex가 뭘 했는지 확인하기 어렵습니다. "보통(Normal)"이면 적당한 양의 로그를 보여주고, "많음(Verbose)"이면 매우 상세한 로그를 보여줍니다. 초보자에게는 "보통(Normal)"을 추천합니다. 뭘 하는지 파악하기에 충분하면서 화면이 너무 복잡하지 않습니다.
• 3 "멀티라인 프롬프트"란?
  기본적으로 Codex에 명령을 입력할 때 한 줄로 씁니다. 하지만 복잡한 요청(예: "이 파일에서 A를 바꾸고, B를 추가하고, 테스트도 만들어줘")은 여러 줄로 쓰는 게 더 명확합니다. 이 설정을 켜면 Enter로 줄바꿈을 하고, Cmd+Enter로 전송할 수 있습니다.
• 4 "Sleep 방지"란?
  Mac은 일정 시간 사용하지 않으면 잠자기 모드로 들어갑니다. 긴 작업 중에 잠자기 모드가 되면 작업이 중단될 수 있습니다. 이 설정을 켜면 Codex가 작업 중일 때 컴퓨터가 잠들지 않습니다.

Notifications (알림 설정)

• 1 작업 완료 알림: Codex에게 코드 작성을 맡기고 다른 일을 하고 있을 때, 작업이 끝나면 macOS 알림 센터를 통해 알려줍니다. 다른 앱에서 일하다가도 바로 확인할 수 있어 편리합니다.
• 2 에러 발생 알림: 작업 중 문제가 생기면 즉시 알림을 보내줍니다. 에러를 빨리 알아야 수정도 빨리 할 수 있으므로 항상 켜두는 것을 권장합니다.

Agent Configuration (에이전트 설정)

Appearance (외관 설정)

• 1 테마 (밝게/어둡게/시스템 자동): 밝은 테마는 낮에, 어두운 테마는 밤에 눈이 편합니다. "시스템 자동"으로 설정하면 Mac의 다크모드 설정에 따라 자동 전환됩니다.
• 2 UI 폰트와 코드 폰트: UI 폰트는 메뉴, 버튼 등의 글꼴이고, 코드 폰트는 코드 편집 영역의 글꼴입니다. 코드 폰트로는 JetBrains Mono나 Fira Code처럼 숫자 0과 영문 O를 구분하기 쉬운 고정폭 폰트를 추천합니다.
• 3 액센트(accent) · 배경(background) · 전경(foreground) 색상 분리: 공식 설정은 베이스 테마 위에 3가지 색상을 각각 따로 조정할 수 있습니다. 강조 색만 브랜드 색으로, 배경은 기본 유지 같은 조합이 가능합니다.
• 4 커스텀 테마 공유: 본인이 설정한 테마(베이스 + 색상 + 폰트 조합)를 친구·팀원과 공유할 수 있습니다 — Settings의 테마 export 기능으로 내보내 같은 회사의 다른 사람이 동일한 외관을 한 번에 가져갈 수 있습니다.
• 5 Codex Pets (애니메이션 컴패니언): Appearance → Pets에서 Wake Pet/Tuck Away Pet으로 켜고 끕니다. 스레드 진행 상태를 작은 오버레이로 표시해 다른 작업을 하면서도 상태를 곁눈으로 확인할 수 있습니다. Composer에 /pet을 입력해도 같은 동작을 합니다. 사용자 정의 펫을 만들고 싶다면 $hatch-pet Skill을 설치하세요.

Git (버전 관리 설정)

• 1 브랜치 이름 규칙: 팀에서 "새 기능은 feat/으로, 버그 수정은 fix/으로 시작하자"라고 정했다면, 이 규칙을 Settings에 등록하세요. Codex가 브랜치를 만들 때 자동으로 규칙을 따릅니다. 예: feat/login-page, fix/typo-readme
• 2 커밋 메시지 템플릿: 커밋 메시지에 일정한 형식을 적용할 수 있습니다. 예를 들어, "[타입] 설명" 형식을 설정하면 Codex가 그 형식에 맞춰 커밋 메시지를 작성합니다. 이렇게 하면 나중에 변경 이력을 찾아보기 훨씬 쉬워집니다.
• 3 Force push 설정: Force push는 원격 저장소의 기록을 강제로 덮어쓰는 위험한 동작입니다. 팀원이 작업한 내용이 사라질 수 있으므로, 이 설정을 비활성화(Off)로 두는 것을 강력히 추천합니다.
• 4 PR(Pull Request) 설명 템플릿: PR을 만들 때 자동으로 들어갈 설명 형식을 지정할 수 있습니다. "어떤 변경을 했는지", "왜 변경했는지", "테스트는 어떻게 했는지"를 정리해두면 코드 리뷰가 훨씬 원활해집니다.

Settings 구조

Settings 주요 항목 비교표

추가 카테고리 7종 (공식 Settings 보강)

공식 Settings 화면은 General/Notifications/Agent configuration/Appearance/Git 외에도 아래 7개 영역을 포함합니다(총 12개 카테고리).

Approval Policy & Sandbox Mode — 독립된 두 축

공식 문서는 두 가지를 독립된 축으로 분리합니다 — Approval Policy는 "언제 사용자에게 묻는가"를, Sandbox Mode는 "Codex가 무엇을 만질 수 있는가"를 결정합니다. CLI에서는 두 축을 직접 플래그로 줄 수 있습니다 — --ask-for-approval <policy> 와 --sandbox <mode>. --full-auto는 --sandbox workspace-write --ask-for-approval on-request의 alias입니다.

Approval Policy

참고: on-failure는 deprecated이며 공식 config-reference는 대화형은 on-request, 비대화형은 never를 권장합니다. { granular = … }로 도구별 세분화도 가능하며, 5개 카테고리(sandbox approvals, execution-policy rules, MCP tool calls, permission requests, skill-script approvals)를 각각 독립 설정할 수 있습니다.

Approvals Reviewer — AI 자동 리뷰어로 승인 라우팅

기본값은 approvals_reviewer = "user"(사용자가 직접 승인). "auto_review"로 두면 리뷰어 에이전트가 먼저 위험을 평가하고, 안전하다고 판단되면 사용자 프롬프트 없이 통과시킵니다. on-request·granular policy처럼 인터랙티브 승인이 활성화된 상황에서만 적용됩니다.

주의: 추가 모델 호출이 발생하므로 비용·지연이 늘어납니다. 또 안전성은 자동 리뷰어 모델의 추론에 의존하므로, 위험이 높은 워크플로에는 사용자 검토와 병행하세요. 기본 정책은 openai/codex 저장소의 policy.md에서 확인할 수 있습니다.

Sandbox Mode

Memories — 스레드 간 컨텍스트 유지

Memories는 사용자가 명시적으로 저장한 장기 기록을 모든 스레드에서 참조하는 기능입니다(공식 features 문서). 새 스레드를 시작해도 "내 기본 패키지 매니저는 pnpm" 같은 사실이 유지됩니다.

• ✓저장 — 채팅 중 자연어로 저장 요청을 하거나(예: "이 정보를 기억해 줘") Settings → Memories에서 직접 입력합니다. 특정 한국어 트리거 문구가 정해진 것은 아닙니다.
• ✓편집/삭제 — Settings → Memories 목록에서 항목별로 수정·삭제 가능.
• ✓AGENTS.md와 차이 — Memories는 사용자 계정 단위 영구 기록, AGENTS.md는 저장소에 커밋되어 팀이 공유하는 프로젝트 컨텍스트입니다.

AGENTS.md 계층 (전역 → 루트 → 가장 가까운 파일)

Codex는 사용자 홈의 전역 파일부터 작업 파일에 가장 가까운 패키지 파일까지를 모두 읽고 순서대로 이어 붙입니다(concatenate). 단일 파일이 다른 파일을 "덮어쓰는" 모델이 아니라, 빈 줄로 합쳐진 뒤 모델 컨텍스트에 들어갑니다 — 따라서 같은 키를 다시 적으면 뒤에 적힌 쪽이 우선합니다.

1. ~/.codex/AGENTS.md — 전역(사용자 계정의 모든 프로젝트에 적용).
2. <repo>/AGENTS.md — 저장소 루트(팀 공통 컨텍스트).
3. <repo>/<package>/AGENTS.md — 모노레포의 패키지별 파일.

각 단계마다 AGENTS.override.md가 먼저 검사되고, 그 다음 AGENTS.md, 그리고 project_doc_fallback_filenames(예: ["TEAM_GUIDE.md", ".agents.md"])에 등록된 파일명이 차례로 검사됩니다. 빈 파일은 건너뛰며, 현재 디렉터리에서 위로 추적하지 않습니다(레포 루트로 한 번만 점프). 이어 붙인 instructions의 총 크기는 project_doc_max_bytes 설정 키(기본 32 KiB)로 제한됩니다.

4-tier 컨텍스트 — Personalization vs Memories vs 저장소 AGENTS.md vs 패키지 AGENTS.md

"내 개인 선호"는 Personalization, "특정 사실 기억(예: 패키지 매니저는 pnpm)"은 Memories, "팀 코드 컨벤션"은 저장소 AGENTS.md, "패키지별 특수 규칙"은 패키지 AGENTS.md로 분리합니다.

추천 초기 설정 가이드 (4단계)

config.toml이란?

# ~/.codex/config.toml 예시 (실제 스키마)
model = "gpt-5-codex"
model_reasoning_effort = "medium"   # minimal | low | medium | high
model_reasoning_summary = "auto"    # auto | concise | detailed | none
model_verbosity = "medium"          # low | medium | high — GPT-5 Responses API verbosity 오버라이드
sandbox_mode = "workspace-write"    # read-only | workspace-write | danger-full-access
approval_policy = "on-request"      # untrusted | on-request | never  ('on-failure'는 deprecated)
approvals_reviewer = "user"         # user | auto_review — auto_review는 리뷰어 에이전트가 먼저 평가
service_tier = "flex"               # flex | fast — fast는 Fast mode 빠른 응답 경로

[features]
hooks = false                       # Hooks 시스템 활성화 (codex_hooks는 deprecated alias)
fast_mode = true                    # Fast mode/service_tier='fast' 경로 (기본 활성)
memories = true                     # 계정 단위 장기 기억 사용
multi_agent = false                 # 멀티/서브 에이전트 기능
personality = true                  # Personalization personality 옵션
undo = true                         # 변경 되돌리기
enable_request_compression = true   # 컨텍스트 압축

[agents]
max_threads = 6                     # 동시에 실행 가능한 서브 에이전트 수 (기본 6)
max_depth = 1                       # 서브 에이전트 중첩 깊이 (root=0, 기본 1)
job_max_runtime_seconds = 1800      # 워커당 최대 실행 시간 (기본 1800초)

[auto_review]
# policy = """
# Block any task that exfiltrates secrets outside the workspace.
# Always require explicit approval for `rm -rf` style commands.
# """

[profiles.review]
model = "gpt-5-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "on-request"

file_opener = "vscode"              # vscode | vscode-insiders | windsurf | cursor | none
web_search = "cached"               # disabled | cached | live  ('live'는 prompt-injection 위험)

[history]
persistence = "save-all"            # save-all | none  (save-all일 때 transcript가 history.jsonl에 저장)

[sandbox_workspace_write]
network_access = false              # 기본 false — 네트워크 차단
writable_roots = []                 # 기본 [] — 워크스페이스 외 추가 쓰기 가능 경로 화이트리스트
exclude_tmpdir_env_var = false      # 기본 false — TMPDIR 환경변수 경로를 쓰기 가능 영역에서 제외할지
exclude_slash_tmp = false           # 기본 false — /tmp 를 쓰기 가능 영역에서 제외할지

[profiles.review]
model = "gpt-5-codex"
model_reasoning_effort = "high"
sandbox_mode = "read-only"
approval_policy = "on-request"

[mcp_servers.docs]                  # stdio 서버
command = "docs-mcp-server"
args = []
env = { DOCS_TOKEN = "..." }
env_vars = ["HOME", "PATH"]         # 자식 프로세스에 전달할 호스트 env 화이트리스트
cwd = "."
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true                      # false면 등록만 하고 비활성화
required = false                    # true면 시작 실패 시 세션 자체를 중단
enabled_tools = ["search", "read"]  # allowlist (지정 안 하면 전체)
disabled_tools = []                 # denylist
[mcp_servers.api]                   # HTTP 서버 예시
url = "https://example.com/mcp"
bearer_token_env_var = "MCP_TOKEN"
http_headers = { "X-Source" = "codex" }
env_http_headers = ["X-Trace-Id"]   # 환경변수로부터 헤더 주입
mcp_oauth_callback_port = 1455
mcp_oauth_callback_url = "http://localhost:1455/callback"

실전 팁

자주 묻는 질문 (FAQ)

• Q1 설정을 잘못 바꿨으면 초기화할 수 있나요?
  네, 가능합니다. 각 설정 항목에는 기본값이 정해져 있으므로, 원래 값으로 되돌리면 됩니다. 만약 config.toml을 수정하다가 문제가 생겼다면, 해당 파일을 삭제하면 Codex가 기본 설정으로 다시 시작합니다. 걱정하지 마세요. 설정은 언제든 바꿀 수 있고, 잘못 바꿔도 코드가 날아가거나 하지 않습니다.
• Q2 설정을 팀원과 공유할 수 있나요?
  config.toml 파일을 프로젝트 저장소에 포함시키면 팀원 모두가 같은 설정을 사용할 수 있습니다. Git 브랜치 규칙이나 커밋 메시지 형식 같은 팀 공통 설정은 이 방법으로 통일하는 것이 좋습니다. 개인 취향(테마, 폰트 등)은 각자의 로컬 설정에서 관리하면 됩니다.
• Q3 어떤 테마가 눈에 편한가요?
  사람마다 다르지만, 일반적으로 밤이나 어두운 환경에서는 어두운 테마(Dark)가 눈의 피로를 줄여줍니다. 밝은 곳에서는 밝은 테마(Light)가 오히려 가독성이 좋습니다. 가장 편한 방법은 "시스템 자동(System)"으로 설정해서 Mac의 다크모드와 연동하는 것입니다. 시간대에 따라 자동 전환되도록 Mac 설정에서 "자동"을 켜두면 더 편리합니다.
• Q4 config.toml을 직접 수정해야 하나요?
  초보자라면 아니요. Settings 화면에서 제공하는 옵션만으로 대부분의 설정을 충분히 조절할 수 있습니다. config.toml은 Settings UI에서 제공하지 않는 고급 옵션을 바꿀 때만 필요합니다. 예를 들어, 특정 AI 모델의 세부 파라미터를 조정하거나, 커스텀 명령을 추가하는 경우입니다. Codex에 충분히 익숙해진 후에 필요할 때 찾아보세요.
• Q5 force push란 뭔가요? 왜 조심해야 하나요?
  force push는 Git 원격 저장소(예: GitHub)에 있는 기록을 내 로컬 기록으로 강제 덮어쓰는 명령입니다. 보통의 push는 "원격에 내 변경사항을 추가"하지만, force push는 "원격의 기록을 무시하고 내 것으로 교체"합니다.
  
  왜 위험한가요? 만약 팀원 A가 코드를 올려놨는데, 내가 force push를 하면 팀원 A의 작업이 통째로 사라질 수 있습니다. 복구가 불가능할 수도 있어서, 대부분의 팀에서는 force push를 금지합니다. Codex Settings에서도 반드시 비활성화(Off)로 설정해 두세요.
• Q6 설정을 바꾸면 바로 적용되나요?
  대부분의 설정은 변경 즉시 적용됩니다. 테마나 폰트 같은 외관 설정은 바로 화면에 반영되고, Git 관련 설정도 다음 작업부터 바로 적용됩니다. config.toml을 수정한 경우에는 Codex를 재시작해야 적용될 수도 있습니다.

다음 단계

장점 / 단점 / 한계점

Hooks — Codex 작동에 사용자 스크립트 끼워 넣기

Hooks는 Codex 세션의 정해진 시점에 사용자가 만든 셸 명령을 실행하는 확장 메커니즘입니다 — 자동 lint, 변경 차단, 알림, 외부 시스템 동기화 같은 워크플로를 직접 끼워 넣을 수 있습니다. 알파 기능이며 활성화에 feature flag가 필요합니다.

활성화 방법

• ✓~/.codex/config.toml에 [features]
hooks = true 추가 (정식 키). codex_hooks는 deprecated 별칭으로 그대로 동작하지만 신규 작성은 hooks를 사용하세요.
• ✓훅 정의는 ~/.codex/hooks.json(사용자) 또는 프로젝트 디렉터리(trusted project로 등록된 경우)의 동일 이름 파일에 작성. 발견 우선순위는 user → project.

6가지 Hook 이벤트

exit code와 timeout

• ✓exit 0 — 통과. Codex가 그대로 진행.
• ✓exit 2 — 차단. stderr로 출력한 메시지가 사용자/모델에게 전달되어 차단 사유로 사용됨.
• ✓그 외 non-zero — 일반 실패로 기록되며 Codex는 진행.
• ✓각 hook의 기본 timeout은 600초이며 hook 정의에서 개별 조정 가능.

최소 예시 (hooks.json)

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        { "type": "command", "command": ".codex/hooks/check_secrets.sh" }
      ]
    }
  ]
}

위 예시는 모든 Bash 실행 직전에 .codex/hooks/check_secrets.sh를 호출하고, 스크립트가 secret 의심 패턴을 감지하면 exit 2 + 안내 메시지로 차단할 수 있게 합니다. 정확한 이벤트별 matcher 스키마와 출력 형식은 공식 Hooks 문서를 확인하세요.