맥락과 통제

12.1맥락의 네 출처

공식코덱스의 맥락은 서로 경쟁하지 않는 층으로 쌓입니다. AGENTS.md가 행동을 규정하고, 메모리가 이전 작업의 맥락을 이어 오고, 스킬이 반복 절차를 담고, MCP가 로컬 작업 공간 밖 시스템에 연결합니다. customization/overview

12.2점진 공개

공식스킬은 점진 공개(progressive disclosure) 방식으로 읽힙니다. 발견 단계에서는 name과 description 메타데이터만 보고, 스킬이 선택되면 SKILL.md를 로드하고, 참조 문서를 읽거나 스크립트를 실행하는 것은 필요할 때뿐입니다. 덕분에 풍부한 워크플로를 가지고 있어도 앞단 맥락이 부풀지 않습니다. customization/overview

관행이 구조를 알면 설계 판단이 바뀝니다. 스킬이 늘어나는 비용은 본문 길이가 아니라 설명 줄의 총합이고, 지침 파일이 늘어나는 비용은 매 턴 전량입니다. 그래서 같은 내용이라도 지침 파일보다 스킬에 두는 편이 싼 경우가 많습니다.

12.3맥락이 찰 때

공식긴 작업에서는 결과·제약·완료 조건을 명시해 코덱스가 다음 단계를 스스로 고르고 언제 끝났는지 판단할 수 있게 합니다. 관련된 일은 같은 채팅에 두되, 독립적으로 병렬 실행할 수 있는 일은 채팅을 나눕니다. 같은 연결 소스에 두 작업이 동시에 쓰기 권한을 갖는 상황은 피합니다. long-running-work

공식CLI에서 전사가 길어지면 /compact로 요약합니다. 코덱스는 자동으로도 압축합니다. developer-commands

관행압축은 정보를 잃습니다. 그래서 압축에 기대기보다 중간 산출물을 파일로 빼는 편이 안전합니다. 조사 결과를 마크다운 한 장으로 쓰게 하고 다음 채팅에서 그 파일을 붙이면, 전사가 아무리 짧아져도 결론이 남습니다. 쿡북이 이 패턴을 규격으로 만들어 둡니다. 실행 계획 문서는 "오직 그 계획서만으로 다시 시작할 수 있어야 한다"를 요구 조건으로 두고, 코드 현대화 사례는 단계마다 산출 파일 하나를 핵심 산출물로 지정합니다. cookbook codex_exec_plans cookbook code_modernization

13.1지침 파일의 자리

공식코덱스는 작업을 시작하기 전에 AGENTS.md를 읽습니다. 발견은 실행마다 한 번 일어나고, TUI에서는 보통 세션을 띄울 때 한 번입니다. 순서는 이렇습니다. agent-configuration/agents-md

공식빈 파일은 건너뛰고, 합쳐진 크기가 project_doc_max_bytes(기본 32 KiB)에 닿으면 더 붙이지 않습니다. 한도에 걸리면 한도를 올리거나 지침을 하위 디렉터리로 쪼갭니다. agent-configuration/agents-md

지금 무엇이 읽히는지 확인하기

# 저장소 루트에서
codex --ask-for-approval never "Summarize the current instructions."

# 하위 디렉터리의 override 가 적용되는지
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

실전같은 저장소에서 두 에이전트에 주는 지침 양이 크게 갈릴 수 있습니다. 이 문서를 쓴 맥의 볼트를 재 보니 루트 CLAUDE.md는 115줄 11,589자인데 AGENTS.md는 9줄 392자였습니다. 약 30배 차이입니다. 코덱스를 나중에 들인 저장소에서 흔한 상태이고, 이것 자체가 "코덱스가 이 저장소에 대해 아는 것이 거의 없다"는 뜻입니다.

두 지침 파일 크기 비교

wc -lc CLAUDE.md AGENTS.md

공식두 명령은 공식 문서의 검증 절차를 그대로 옮긴 것입니다. 전역 파일이 먼저, 저장소 루트가 그다음, 가장 가까운 override가 마지막으로 보고돼야 정상입니다. agent-configuration/agents-md

13.2무엇을 적는가

공식공식 문서는 AGENTS.md를 "에이전트용 README"에 비유하고 작게 유지하라고 명시합니다. 매번 지켰으면 하는 규칙만 넣습니다. customization/overview

공식처음 만들 때는 CLI의 /init이 현재 디렉터리에 뼈대를 만들어 줍니다. 다만 공식 문서는 그 결과를 그대로 두지 말고 팀이 실제로 빌드·테스트·리뷰·배포하는 방식에 맞게 고치라고 덧붙입니다. best-practices

~/.codex/AGENTS.md (전역, 개발자 개인 기준)

# ~/.codex/AGENTS.md

## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

공식전역 파일과 저장소 파일의 역할은 갈립니다. 전역 파일은 코덱스가 나에게 어떻게 소통할지(리뷰 스타일, 자세함, 기본값)를 잡고, 저장소 파일은 팀과 코드베이스 규칙에 집중합니다. customization/overview

13.3언제 갱신하는가

공식갱신 신호가 문서에 네 가지로 정리돼 있습니다. customization/overview

• 같은 실수 반복. 에이전트가 같은 실수를 반복하면 규칙을 추가합니다.
• 너무 많이 읽음. 맞는 파일을 찾긴 하는데 문서를 과하게 읽으면 라우팅 지침(어느 디렉터리·파일을 우선할지)을 넣습니다.
• 같은 PR 피드백 반복. 같은 지적을 두 번 이상 남기게 되면 규칙으로 굳힙니다.
• 표류 점검 자동화. 예약 작업으로 지침 결손을 주기적으로 찾아 무엇을 추가할지 제안하게 합니다.

공식코덱스가 코드베이스에 대해 틀린 가정을 하면 AGENTS.md에서 바로잡고, 그 수정이 남도록 코덱스에게 AGENTS.md를 갱신하라고 시킵니다. 피드백 루프로 다룹니다. GitHub PR 코멘트에서는 @codex add this to AGENTS.md처럼 위임할 수도 있습니다. customization/overview

공식지침만으로 끝내지 말고 강제하는 인프라와 짝지으라고 문서가 권합니다. pre-commit 훅, 린터, 타입 체커가 사람 눈에 닿기 전에 잡아 주면 시스템이 재발을 막는 쪽으로 똑똑해집니다. customization/overview

13.4디렉터리별 지침

공식특정 팀에 다른 규칙이 필요하면 그 디렉터리에 AGENTS.override.md를 둡니다. 같은 디렉터리에 AGENTS.md가 있어도 override가 이깁니다. 코덱스는 현재 디렉터리에 닿으면 탐색을 멈추므로, override는 특수 작업에 최대한 가까이 둡니다. agent-configuration/agents-md

services/payments/AGENTS.override.md

# services/payments/AGENTS.override.md

## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.

공식저장소가 이미 다른 이름을 쓰고 있으면 폴백 목록에 추가합니다. 목록에 없는 파일명은 지침 탐색에서 무시됩니다. agent-configuration/agents-md

~/.codex/config.toml

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

13.5메모리

공식로컬 코덱스 메모리는 기본이 꺼짐입니다. 데스크톱 앱의 Settings > Personalization에서 켜거나 설정 파일에 기능 플래그를 넣습니다. customization/memories

config.toml

[features]
memories = true

공식켜면 코덱스가 지난 채팅에서 유용한 맥락을 로컬 메모리 파일로 만듭니다. 진행 중이거나 짧은 세션은 건너뛰고, 생성되는 필드에서 비밀을 지우고, 채팅이 끝난 즉시가 아니라 배경에서 갱신합니다. 아직 진행 중인 작업을 요약하지 않으려고 충분히 유휴 상태가 될 때까지 기다립니다. customization/memories

공식저장 위치는 코덱스 홈 아래 ~/.codex/memories/입니다. 요약·지속 항목·최근 입력·근거가 들어갑니다. 문제를 볼 때나 코덱스 홈을 공유하기 전에 열어 볼 수는 있지만, 주된 통제 수단으로 손편집에 기대지 말라고 문서가 명시합니다. customization/memories

공식채팅 단위 제어는 /memories입니다. 이 채팅이 기존 메모리를 쓸지, 이후 메모리의 입력이 될지를 고릅니다. 채팅 단위 선택은 전역 설정을 바꾸지 않습니다. customization/memories

13.6크로니클

공식크로니클은 옵트인 연구 프리뷰입니다. macOS의 ChatGPT Pro 구독자에게만 제공되고 화면 기록·손쉬운 사용 권한이 필요합니다. 화면 맥락으로 메모리를 보강해, 사용자가 맥락을 다시 설명할 필요를 줄이는 것이 목적입니다. customization/chronicle

공식켜기 전에 알아야 할 대가가 문서에 명시돼 있습니다. 한도를 빠르게 소모하고, 프롬프트 인젝션 위험이 커지며, 메모리가 기기에 암호화되지 않은 채 저장됩니다. 배경에서 샌드박스 에이전트를 돌려 화면 캡처로 메모리를 만들기 때문에 한도 소모가 빠릅니다. customization/chronicle

공식메뉴 막대 아이콘에서 Pause Chronicle로 언제든 멈출 수 있습니다. 회의 전이나 민감한 내용을 볼 때 멈추라고 문서가 안내하고, 다른 사람과의 회의·대화를 동의 없이 기록하는 데 쓰지 말라고 명시합니다. customization/chronicle

13.7개인화

공식모든 채팅에 적용될 선호는 Settings > Personalization의 커스텀 지시에 두고, 지금 채팅에만 해당하는 것은 프롬프트에 둡니다. prompting personalize

공식소통 스타일은 설정 파일에서도 정합니다. 세션 안에서는 /personality로 덮습니다. config-file/config-basic

config.toml

personality = "friendly"   # "pragmatic" 또는 "none"

13.8무엇을 어디에 둘까

세 곳에 같은 것을 두면 관리 면이 셋으로 늘어납니다. 판정표는 이렇습니다.

14.1승인 모드 전체

공식승인 모드는 코덱스가 스스로 할 수 있는 것과 검토가 필요한 것의 경계입니다. 데스크톱 앱과 IDE 확장은 컴포저 아래 권한 컨트롤, CLI는 /permissions로 엽니다. 대부분의 작업은 Ask for approval로 시작하라고 문서가 권합니다. permission-modes

공식설정 키로 보면 승인 정책은 셋입니다. untrusted는 알려진 안전한 읽기 동작만 자동으로 돌리고, 상태를 바꾸거나 외부 실행 경로를 부르는 명령(예: 파괴적 git 동작, git 출력·설정 덮어쓰기 플래그)은 승인을 받습니다. on-request는 필요할 때 묻습니다. never는 묻지 않습니다. agent-approvals-security config-file/config-basic

공식중간 지대로 세분화 승인 정책이 있습니다. 카테고리별로 대화형 유지 여부를 나눠, 나머지는 자동 거절합니다. 대상 카테고리는 샌드박스 승인, execpolicy 규칙 프롬프트, MCP 프롬프트, request_permissions 프롬프트, 스킬 스크립트 승인입니다. agent-approvals-security

config.toml

approval_policy = { granular = {
  sandbox_approval = true,
  rules = true,
  mcp_elicitations = true,
  request_permissions = false,
  skill_approval = false
} }

14.2승인과 샌드박스의 관계

근거는 두 문서가 같은 말을 합니다. agent-approvals-security permission-modes

공식기본 권고는 폴더 상태에 따라 갈립니다. 버전 관리되는 폴더는 Auto(작업 공간 쓰기 + 요청 시 승인), 아닌 폴더는 read-only입니다. 설정에 따라 작업 디렉터리를 명시적으로 신뢰하기 전까지 read-only로 시작할 수도 있습니다. agent-approvals-security

공식앱·MCP 도구 호출도 승인 대상입니다. 셸 명령이나 파일 변경이 아니어도, 도구가 부수효과를 알리면 승인을 요청할 수 있습니다. 파괴적 주석을 단 도구 호출은 다른 힌트(예: 읽기 전용 힌트)를 함께 달고 있어도 항상 승인이 필요합니다. agent-approvals-security

조합표는 L1 8.3에 있습니다. 이 절에서는 조합을 고르는 기준만 둡니다.

14.3규칙으로 명령 허용하기

공식규칙(rules)은 샌드박스 밖에서 코덱스가 실행할 수 있는 명령을 통제합니다. 실험 기능이라 바뀔 수 있습니다. agent-configuration/rules

~/.codex/rules/default.rules

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "Viewing PRs is allowed with approval",
    match = [
        "gh pr view 7888",
        "gh pr view --repo openai/codex",
    ],
    not_match = [
        "gh pr --repo openai/codex view 7888",
    ],
)

공식복합 명령이 위험을 숨기는 문제를 코덱스가 따로 처리합니다. bash -lc·bash -c와 zsh·sh 대응이 특별 취급됩니다. 스크립트가 단순 단어들이 안전한 연산자(&&, ||, ;, |)로만 이어진 선형 사슬이면 개별 명령으로 쪼개 각각 평가하고, 가장 제한적인 결과를 씁니다. agent-configuration/rules

공식덕분에 git add를 허용해 두어도 git add . && rm -rf /는 자동 허용되지 않습니다. rm -rf / 부분이 따로 평가되기 때문입니다. 반대로 리다이렉션·치환·환경변수·와일드카드·제어 흐름이 들어가면 쪼개지 않고 호출 전체를 하나로 보고 규칙을 적용합니다(보수적으로). agent-configuration/rules

저장 전에 규칙을 시험합니다

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

공식코덱스는 시작할 때 활성 설정 계층마다 rules/를 훑습니다. 프로젝트 로컬 규칙(.codex/rules/)은 그 프로젝트의 .codex/ 계층이 신뢰될 때만 로드됩니다. TUI에서 명령을 허용 목록에 추가하면 사용자 계층 ~/.codex/rules/default.rules에 기록됩니다. agent-configuration/rules

14.4권한 프로파일 (베타)

공식권한 프로파일은 로컬 명령에 최소 권한 경계를 적용하는 이름 붙은 정책입니다. 무엇을 읽고 쓸 수 있는지 정하는 파일시스템 규칙과, 어느 목적지에 닿을 수 있는지 정하는 네트워크 규칙을 묶습니다. macOS·Linux·WSL·네이티브 윈도우에서 지원됩니다. permissions

config.toml

default_permissions = "project-edit"

[permissions.project-edit.workspace_roots]
"~/code/app" = true

관행이 배타성이 실무에서 가장 자주 걸리는 지점입니다. 프로파일을 새로 썼는데 적용이 안 되면, 대개 어딘가에 sandbox_mode가 남아 있습니다. /debug-config로 계층을 먼저 보고 그 줄부터 지웁니다.

14.5자동 검토

공식자동 검토(auto-review)는 샌드박스 경계에서의 수동 승인을 별도 검토 에이전트로 대체합니다. 주 에이전트는 같은 샌드박스, 같은 승인 정책, 같은 네트워크·파일시스템 제한 안에 그대로 있습니다. 달라지는 것은 누가 검토하는가뿐입니다. sandboxing/auto-review

config.toml

approval_policy = "on-request"
approvals_reviewer = "auto_review"   # 기본값은 "user"

공식흐름은 다섯 단계입니다. 주 에이전트가 read-only 또는 workspace-write 안에서 일하다가, 경계를 넘어야 하면 승인을 요청하고, 그 요청이 검토 에이전트로 라우팅되고, 검토자가 판단과 사유를 돌려주고, 승인되면 계속하고 거부되면 주 에이전트는 실질적으로 더 안전한 경로를 찾거나 멈춰 사용자에게 묻습니다. sandboxing/auto-review

공식검토자 정책은 데이터 유출, 자격증명 탐색, 지속적 보안 약화, 파괴적 동작을 봅니다. 저위험·중위험은 정책이 허용하면 통과하고, 치명적 위험은 거부합니다. 고위험은 충분한 사용자 인가가 있고 일치하는 거부 규칙이 없어야 통과합니다. 프롬프트 구성·검토 세션·파싱 실패는 닫힘으로 실패합니다. 타임아웃은 따로 표시되지만 동작은 여전히 실행되지 않습니다. agent-approvals-security

공식거부된 동작을 한 번 재시도하려면 /approve를 씁니다. 자동 검토는 모델 호출을 더 쓰므로 사용량이 늘 수 있습니다. developer-commands agent-approvals-security

14.6위험 경계 설계

관행규칙을 쓸 때 실수하기 쉬운 지점은 "무엇을 허용할까"부터 생각하는 것입니다. 순서를 뒤집으면 목록이 훨씬 짧아집니다. 되돌릴 수 없는 것부터 forbidden으로 못박고, 나머지는 기본값(승인 요청)에 맡깁니다. 되돌릴 수 없는 것의 목록은 저장소마다 다르지만 대개 배포, 외부 발송, 과금, 원격 삭제, 자격증명 회전입니다.

공식forbidden을 쓸 때는 justification에 대안을 함께 적으라고 문서가 권합니다. 예를 들어 "grep 대신 rg를 쓰세요"처럼. 차단만 하면 코덱스가 우회를 시도하고, 대안을 주면 바로 다음 행동으로 갑니다. agent-configuration/rules

실전규칙 파일이 아예 없는 상태가 기본값입니다. 이 맥에는 ~/.codex/rules 디렉터리 자체가 없었고, 그것은 allow도 forbidden도 0건이라는 뜻입니다. 이 상태에서는 되돌릴 수 없는 명령을 막는 장치가 승인 화면뿐이고, 승인 화면은 사람이 매번 제대로 읽어야만 작동합니다.

지금 규칙이 몇 건인지

ls ~/.codex/rules 2>/dev/null | wc -l
grep -c "prefix_rule" ~/.codex/rules/*.rules 2>/dev/null || echo 0

15.1샌드박스가 하는 일

공식샌드박스는 에이전트가 기계 전체에 접근하지 않으면서도 자율적으로 움직일 수 있게 하는 경계입니다. 데스크톱 앱·CLI·IDE 확장의 로컬 채팅에서 명령이 돌 때, 그 명령은 기본적으로 제한된 환경 안에서 돕니다. sandboxing

공식중요한 점은 샌드박스가 내장 파일 조작만이 아니라 파생된 명령 전체에 적용된다는 것입니다. 에이전트가 git, 패키지 매니저, 테스트 러너를 돌리면 그 명령들도 같은 경계를 물려받습니다. sandboxing

공식목적은 두 가지로 정리됩니다. 승인 피로를 줄이는 것(저위험 명령마다 확인받지 않아도 됩니다)과 신뢰 모델을 분명히 하는 것(에이전트의 의도를 믿는 것이 아니라 강제된 한계 안에서 돈다는 것을 믿습니다). sandboxing

공식기본 workspace-write에서는 네트워크가 꺼져 있습니다. 켜려면 설정이 필요합니다. agent-approvals-security

config.toml

[sandbox_workspace_write]
network_access = true

15.2OS별 구현

공식강제 방식이 OS마다 다릅니다. 개념은 같지만 준비물이 다릅니다. agent-approvals-security sandboxing

Linux · WSL2 준비

# Ubuntu · Debian
sudo apt install bubblewrap

# Fedora
sudo dnf install bubblewrap

공식코덱스는 PATH에서 처음 찾은 bwrap을 씁니다. 없으면 번들 헬퍼로 폴백하지만 그 헬퍼는 비특권 사용자 네임스페이스 생성을 지원해야 합니다. bwrap이 없거나 네임스페이스를 못 만들면 시작할 때 경고가 뜹니다. sandboxing

공식Ubuntu 24.04에서는 bubblewrap을 깔아도 네임스페이스 경고가 남을 수 있습니다. 추가 AppArmor 프로파일을 로드합니다. Ubuntu 25.04는 apparmor 패키지에 프로파일이 포함돼 별도 설정 없이 동작합니다. sandboxing

Ubuntu 24.04

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

샌드박스 안에서 명령이 어떻게 도는지 직접 봅니다

# macOS
codex sandbox macos [--permissions-profile <name>] [--log-denials] [COMMAND]...
# Linux
codex sandbox linux [--permissions-profile <name>] [COMMAND]...
# Windows
codex sandbox windows [--permissions-profile <name>] [COMMAND]...

15.3윈도우 샌드박스

공식네이티브 윈도우에서는 windows 테이블로 샌드박스 모드를 정합니다. elevated가 권장이고, 관리자 권한이 없거나 승격 설정이 실패할 때만 unelevated를 씁니다. config-file/config-basic windows/windows-sandbox

config.toml

[windows]
sandbox = "elevated"      # 권장
# sandbox = "unelevated"  관리자 권한이 없을 때의 폴백

공식기능이 떨어진 윈도우 샌드박스를 승격 설정으로 교체하려면 CLI에서 /setup-default-sandbox를 씁니다. 읽기 경로를 하나 더 열어야 하면 /sandbox-add-read-dir입니다(둘 다 윈도우 전용). developer-commands

15.4WSL에서 돌리기

공식윈도우에서 WSL2를 쓰면 리눅스 샌드박스 구현이 적용됩니다. WSL1은 코덱스 0.114까지만 지원됐고, 0.115부터 리눅스 샌드박스가 bwrap으로 옮겨 가면서 지원이 끊겼습니다. agent-approvals-security

공식IDE 확장을 윈도우에서 쓰면 WSL2를 직접 지원합니다. 아래 설정을 넣으면 WSL2가 있을 때 에이전트를 그 안에 유지하므로, 호스트 OS가 윈도우여도 명령·승인·파일시스템 접근이 리눅스 샌드박스 의미론을 물려받습니다. agent-approvals-security windows/wsl

VS Code settings.json

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

15.5격리 선택지 비교

샌드박스는 격리의 한 층입니다. 코덱스에서 격리는 네 갈래로 갈립니다.

공식데스크톱 앱에서 코덱스 채팅을 시작할 때 고르는 환경은 로컬·워크트리·클라우드 셋입니다. 앞의 둘은 사용자 컴퓨터에서 돕니다. environments/modes

공식컨테이너를 의도한 보안 경계로 쓸 때는 그 안에서 코덱스를 --sandbox danger-full-access로 돌립니다. 그래야 코덱스가 두 번째 샌드박스 층을 만들려 하지 않습니다. 다만 컨테이너가 격리를 제공하도록 먼저 구성해야 합니다. agent-approvals-security

16.1설정 계층과 우선순위

공식코덱스는 여러 위치에서 설정을 읽습니다. 개인 기본값은 ~/.codex/config.toml, 프로젝트 덮어쓰기는 저장소 안의 .codex/config.toml입니다. 보안상 프로젝트 .codex/ 계층은 그 프로젝트를 신뢰할 때만 로드됩니다. config-file/config-basic configuration

공식프로젝트를 신뢰하지 않음으로 표시하면 프로젝트 범위 .codex/ 계층 전체가 건너뛰어집니다. 프로젝트 로컬 설정·훅·규칙이 여기 포함됩니다. 사용자·시스템 설정은 그대로 로드됩니다(사용자·전역 훅과 규칙 포함). config-file/config-basic

지금 어느 계층이 이겼는지 봅니다

/debug-config

실전설정 파일이 있다고 설정이 설계된 것은 아닙니다. 이 맥의 ~/.codex/config.toml은 71줄 2,678바이트인데, 최상위 키는 notify 하나뿐이고 나머지는 전부 테이블 15개([marketplaces] 2 · [plugins] 8 · [features] 1 · [mcp_servers] 3 · [desktop] 1)였습니다. model·approval_policy·sandbox_mode·web_search는 한 줄도 없었습니다. 앱이 플러그인을 켜고 끄며 쓴 값만 쌓인 상태입니다.

최상위 키와 테이블을 갈라 세기

# 테이블 밖(최상위)에 실제로 적힌 키
awk '/^\[/{t=1} !t && /^[a-z_]+ *=/{print $1}' ~/.codex/config.toml

# 테이블 목록
grep '^\[' ~/.codex/config.toml

16.2config.toml 기본

공식사람들이 가장 자주 바꾸는 항목들입니다. config-file/config-basic

~/.codex/config.toml

model = "gpt-5.6"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "pragmatic"

공식IDE 확장에서 설정 파일을 열려면 오른쪽 위 톱니 아이콘에서 Codex Settings > Open config.toml, 데스크톱 앱에서는 Settings > Configuration > Open config.toml입니다. CLI와 IDE 확장은 같은 설정 계층을 씁니다. config-file/config-basic best-practices

공식기능 플래그는 [features] 테이블에서 켜고 끕니다. 자주 손대는 것만 추립니다. 생략하면 기본값이 유지됩니다. config-file/config-basic

켜고 끄기

# 설정 파일에서
[features]
memories = true

# 명령줄에서 (여러 개면 --enable 을 반복)
codex --enable memories --enable hooks

16.3고급 구성

공식프로파일, 모델 제공자, 승인·샌드박스 정책, MCP 등록, 셸 환경 정책 같은 것들이 고급 구성 문서에 모여 있습니다. 여기서는 자주 쓰이는 둘만 짚습니다. config-file/config-advanced

공식첫째는 셸 환경 정책입니다. 어떤 환경 변수를 파생 명령에 넘길지 통제합니다. ignore_default_excludes는 기본이 true이고, 이 값은 이름에 KEY·SECRET·TOKEN이 들어간 변수의 자동 필터링을 건너뜁니다. 자동 필터링을 원하면 false로 둡니다. config-file/config-basic

config.toml

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

공식둘째는 로그 디렉터리입니다. log_dir을 명시하면 그 디렉터리에 평문 TUI 로그(codex-tui.log)가 함께 켜집니다. 지침 파일이 실제로 무엇이 로드됐는지 감사할 때 이 로그를 씁니다. config-file/config-basic

codex -c log_dir=./.codex-log

16.4키 레퍼런스 읽는 법

공식지원되는 설정 키 전량과 requirements.toml 스키마는 공식 설정 레퍼런스가 정본입니다. 이 가이드는 그 목록을 복사하지 않습니다. config-file/config-reference

관행레퍼런스를 통째로 읽는 것보다 지금 세션이 실제로 쓰는 값에서 거꾸로 가는 편이 빠릅니다. /status로 활성값을 보고, /debug-config로 그 값이 어느 계층에서 왔는지 보고, 바꾸고 싶은 것만 레퍼런스에서 찾습니다.

공식관리형 기기에서는 조직이 requirements.toml로 제약을 강제할 수 있습니다. 예를 들어 approval_policy = "never"나 sandbox_mode = "danger-full-access"를 금지할 수 있습니다. 설정을 아무리 고쳐도 안 먹으면 이쪽을 봅니다. config-file/config-basic

16.5환경 변수

공식기기·세션마다 달라지는 값은 환경 변수로 둡니다. 첫 달에 실제로 쓰이는 것은 셋입니다. config-file/environment-variables

프로젝트 전용 코덱스 홈으로 실행

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

16.6샘플에서 시작하기

공식공식 문서에 주석이 달린 전체 예제 설정이 있습니다. 처음부터 쓰는 것보다 그 파일을 복사해 필요 없는 줄을 지우는 편이 빠릅니다. config-file/config-sample

공식공식 베스트 프랙티스의 권장 배치는 이렇습니다. 개인 기본값은 ~/.codex/config.toml, 저장소 고유 동작은 .codex/config.toml, 명령줄 덮어쓰기는 일회성 상황에만. best-practices

16.7표면별 설정 화면

공식설정 파일과 별개로 표면마다 자기 설정 화면이 있습니다. IDE 확장 설정과 데스크톱 앱 설정은 각각 별도 레퍼런스로 문서화돼 있습니다. developer-settings reference/settings

관행같은 것을 두 곳에서 설정할 수 있을 때는 설정 파일 쪽을 정본으로 두는 편이 낫습니다. 파일은 저장소나 dotfiles로 복제할 수 있고 화면 설정은 기기에 갇힙니다.

16.8여러 기기에서 같은 설정

관행코덱스 홈은 파일 몇 개로 이뤄져 있어 동기화가 간단합니다. 다만 통째로 옮기면 안 되는 것이 섞여 있습니다.

인증 파일 취급의 근거는 인증 문서입니다. auth

실전이 맥에서는 자격증명이 파일 기반으로 저장돼 있었습니다. ~/.codex/auth.json이 -rw------- 권한의 4,322바이트 파일로 존재합니다. cli_auth_credentials_store를 설정하지 않았으므로 기본 동작이 파일 경로를 탄 것이고, OS 자격증명 저장소로 옮기려면 그 키를 "keyring"으로 명시해야 합니다.

지금 어디에 저장돼 있는지 확인

stat -f "%Sp %z bytes" ~/.codex/auth.json 2>/dev/null || echo "파일 없음(자격증명 저장소 사용 중)"
grep -n cli_auth_credentials_store ~/.codex/config.toml || echo "설정 없음(기본값)"

17.1위협 모델

공식가장 현실적인 위협은 프롬프트 인젝션입니다. 네트워크 접근이나 웹 검색을 켜면 에이전트가 신뢰할 수 없는 지시를 가져와 따라갈 수 있다고 공식 문서가 명시합니다. 웹 결과는 전부 신뢰할 수 없는 입력으로 다룹니다. agent-approvals-security web-search

공식기본 방어가 세 층입니다. 네트워크가 기본으로 꺼져 있고, 샌드박스가 닿을 수 있는 범위를 묶고, 승인 정책이 경계를 넘을 때 멈춥니다. 캐시 웹 검색이 기본인 것도 같은 이유입니다. 임의의 실시간 페이지 대신 색인된 결과를 돌려주므로 노출이 줄어듭니다. agent-approvals-security

17.2안전 운영 수칙

공식네트워크를 열어야 할 때는 전부 여는 대신 정책으로 묶습니다. features.network_proxy는 이미 켜진 네트워크 접근을 제약할 뿐이고 그 자체가 접근을 주지는 않습니다. agent-approvals-security

config.toml

[features.network_proxy]
enabled = true
domains = { "api.openai.com" = "allow", "example.com" = "deny" }

공식도메인 규칙은 허용 목록 우선입니다. 정확한 호스트는 자기 자신만, *.example.com은 하위 도메인만(example.com 자체는 아님), **.example.com은 최상위와 하위 모두를 매치합니다. 전역 * 허용은 거부되지 않은 모든 공개 호스트를 매치하므로 넓은 접근으로 취급하고 가능한 한 좁힙니다. deny가 항상 allow를 이깁니다. agent-approvals-security

공식로컬·사설 목적지는 기본으로 막혀 있습니다(allow_local_binding = false). 와일드카드는 로컬 예외로 인정되지 않고, 호스트명이 로컬·사설 IP로 해석되면 허용 목록에 맞아도 계속 막힙니다. DNS 리바인딩 방어로 조회 실패·타임아웃은 차단되고 비공개 주소로 해석되는 호스트명도 차단됩니다. 다만 문서는 이것이 위험을 줄일 뿐 없애지는 못한다고 명시합니다. agent-approvals-security

관행자격증명은 설정이 아니라 환경에서 격리하는 편이 확실합니다. 셸 환경 정책의 자동 필터링을 켜 두고(ignore_default_excludes = false), 비밀은 저장소 밖에 두고, .env류를 읽어야 하는 작업은 규칙으로 명시적 승인 대상으로 만듭니다.

17.3사이버 안전 정책

공식보안 작업을 시킬 때는 별도 경로가 있습니다. 인가된 사이버보안 작업을 범위가 정해진 접근·격리·자동 검토와 함께 다루는 방식입니다. cyber-safety

조직 차원의 통제는 L6 39장에서 다룹니다. 개인 사용자가 알아 둘 것은 하나입니다. 보안 성격의 작업은 일반 작업과 같은 승인 설정으로 돌리지 않습니다.

17.4개인 설정에서 조직 설정으로

공식어떤 것은 개인이 정하고 어떤 것은 조직이 정합니다. 관리형 환경에서는 인증 방식이나 워크스페이스가 강제될 수 있고, 활성 자격증명이 제약과 맞지 않으면 코덱스가 로그아웃시키고 종료합니다. auth

관리형 설정 예 (조직이 배포)

forced_login_method = "chatgpt"        # 또는 "api"
forced_chatgpt_workspace_id = "00000000-0000-0000-0000-000000000000"

공식조직 통제면 전체(권한·보안·안전)는 별도 문서가 정리합니다. 개인 설정이 안 먹는 것처럼 보일 때 이쪽을 의심합니다. security-administration