확장

18.1확장 수단 6종

공식코덱스를 팀의 방식에 맞추는 층은 서로 경쟁하지 않고 보완합니다. AGENTS.md가 행동을 규정하고, 메모리가 로컬 맥락을 이어 오고, 스킬이 반복 절차를 담고, MCP가 외부 시스템을 연결하고, 서브에이전트가 작업을 위임합니다. customization/overview

공식여기에 두 가지가 더 붙습니다. 스킬과 MCP를 묶어 배포하는 플러그인, 그리고 생애주기 시점에 스크립트를 끼워 넣는 훅입니다. plugins hooks skills-and-plugins developers

실전여섯 수단이 고르게 쓰이지는 않습니다. 이 문서를 쓴 맥의 코덱스 홈을 재 보니 플러그인 8개가 켜져 있는데 그중 전부가 OpenAI 번들·퍼스트파티 마켓플레이스(openai-bundled·openai-primary-runtime)에서 온 것이고, 자작 스킬 0개, 훅 0개, 규칙 0개, MCP 서버 2개였습니다. 설치는 쉽고 제작은 어렵다는 기울기가 그대로 드러납니다. 이 편의 목적은 그 기울기를 뒤집는 것입니다.

지금 내 확장 자산 세기

grep -c '^\[plugins\.' ~/.codex/config.toml
ls ~/.agents/skills 2>/dev/null | wc -l
ls ~/.codex/hooks.json 2>/dev/null | wc -l
ls ~/.codex/rules 2>/dev/null | wc -l
grep -c '^\[mcp_servers\.[a-z_-]*\]' ~/.codex/config.toml

18.2무엇을 언제 쓰나

판정은 질문 네 개로 갈립니다.

관행가장 자주 저지르는 잘못된 배치는 절차를 지침 파일에 쓰는 것입니다. 매 턴 토큰을 쓰면서도 그 절차가 필요 없는 대부분의 작업에서 잡음이 됩니다. 반대 방향 실수는 필수 규칙을 스킬에 두는 것입니다. 설명이 안 맞으면 안 불립니다. 쿡북의 실행 계획 사례가 이 배치를 그대로 보여 줍니다. AGENTS.md에는 "복잡한 기능에는 실행 계획을 쓴다"는 짧은 규칙 한 줄만 두고 절차 전량은 별도 파일에 둡니다. 프롬프팅 가이드는 지침 파일이 매 대화에 사용자 메시지로 주입된다는 것을 설명해 그 비용이 어디서 나오는지도 보여 줍니다. cookbook codex_exec_plans cookbook codex_prompting_guide

18.3공식이 권하는 순서

공식공식 문서는 확장을 쌓는 순서를 넷으로 제시합니다. customization/overview

1. AGENTS.md로 저장소 관례를 따르게 합니다. pre-commit 훅과 린터를 함께 붙여 규칙을 강제합니다.
2. 이미 있는 워크플로면 플러그인을 먼저 설치합니다. 없으면 스킬을 만들고, 공유하고 싶어지면 플러그인으로 포장합니다.
3. 외부 시스템(Linear, GitHub, 문서 서버, 디자인 도구)이 필요해지면 MCP를 붙입니다.
4. 잡음이 많거나 전문화된 작업을 넘길 준비가 되면 서브에이전트를 씁니다.

19.1스킬이란

공식스킬은 지시·자료·선택적 스크립트를 묶어 워크플로를 안정적으로 따르게 하는 단위입니다. 열린 에이전트 스킬 표준(agentskills.io) 위에 서 있습니다. 데스크톱 앱·CLI·IDE 확장에서 쓰이고, 플러그인에 담긴 스킬은 ChatGPT 웹·데스크톱·모바일의 Chat과 Work에서도 쓰입니다. build-skills

공식발화 방식은 둘입니다. 명시 호출은 ChatGPT에서 @, 코덱스 CLI·IDE 확장에서 /skills 또는 $로 스킬을 언급하는 것이고, 암묵 호출은 작업이 스킬 description과 맞을 때 코덱스가 스스로 고르는 것입니다. build-skills

19.2폴더 구조

공식스킬은 SKILL.md 하나와 선택적 하위 폴더로 이뤄진 디렉터리입니다. SKILL.md는 name과 description을 반드시 담아야 합니다. build-skills

my-skill/SKILL.md

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

공식공식 문서의 예시 스킬은 커밋 정리입니다. 실제로 이 정도 길이면 충분합니다. customization/overview

commit 스킬

---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---

1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.

19.3트리거 설계

공식암묵 호출은 description에 달려 있으므로, 범위와 경계가 분명한 간결한 설명을 씁니다. 핵심 사용 사례와 트리거 단어를 앞쪽에 배치해야, 설명이 줄어들어도 호스트가 매칭할 수 있습니다. build-skills

공식근거는 스킬 문서입니다. 선택된 스킬의 SKILL.md 전문은 이 예산과 무관하게 그대로 읽힙니다. build-skills

관행이 예산 구조가 설계를 바꿉니다. 스킬을 늘릴수록 각 설명이 짧아지므로, 설명 앞머리에 트리거를 두지 않은 스킬부터 안 불리기 시작합니다. 스킬이 열 개를 넘어가면 설명 첫 문장을 "무엇을 하는가 + 언제 쓰는가"로 압축하는 것이 실질적인 유지 작업이 됩니다.

공식공식 베스트 프랙티스는 스킬 하나를 한 가지 일에 묶고, 구체 사용 사례 두세 개로 시작하고, 입출력을 분명히 하고, 사용자가 실제로 말할 법한 트리거 문구를 설명에 넣으라고 권합니다. best-practices

19.4전역 스킬과 저장소 스킬

공식코덱스는 저장소·사용자·관리자·시스템 위치에서 스킬을 읽습니다. 저장소의 경우 현재 작업 디렉터리부터 저장소 루트까지 각 디렉터리의 .agents/skills를 훑습니다. 이름이 같은 스킬이 둘이면 병합하지 않고 둘 다 선택기에 나타납니다. build-skills

공식심볼릭 링크된 스킬 폴더도 지원하고 링크 대상을 따라갑니다. 스킬 변경은 자동으로 감지되며, 반영되지 않으면 코덱스를 재시작합니다. build-skills

공식지우지 않고 끄려면 설정에 항목을 넣습니다. 바꾼 뒤에는 재시작합니다. build-skills

~/.codex/config.toml

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

19.5첫 스킬 만들기 실습

공식만드는 경로가 셋입니다. 워크플로를 말로 설명하기보다 보여 주는 편이 쉬우면 기록과 재생을 쓰고, 설명하는 편이 낫다면 내장 생성기 $skill-creator를 부르고, 손으로 만들려면 폴더에 SKILL.md를 씁니다. 생성기는 무엇을 하는 스킬인지, 언제 발동해야 하는지, 스크립트를 포함할지 물어봅니다. 기본은 지시만 담는 형태입니다. build-skills

CLI에서 생성기 부르기

$skill-creator

공식다른 사람이 만든 스킬을 로컬에 설치하려면 $skill-installer를 씁니다. 다른 저장소에서 받아오도록 시킬 수도 있습니다. 다만 이것은 로컬 실험용 경로이고, 자기 스킬을 배포할 때는 플러그인이 정본입니다. build-skills

예: linear 스킬 설치

$skill-installer linear

19.6커스텀 프롬프트에서 이관

공식커스텀 프롬프트는 폐기됐습니다. 재사용 프롬프트는 스킬을 씁니다. custom-prompts

공식다른 에이전트에서 넘어오는 경우 /import가 슬래시 명령을 스킬로 옮겨 줍니다. 다만 인자·셸 치환·파일 경로 자리표시자에 의존하던 프롬프트 템플릿은 가져온 뒤 검토하라고 문서가 명시합니다. import

19.7스킬 안티패턴

공식공식 문서의 판단 기준은 한 줄입니다. 같은 프롬프트를 계속 재사용하거나 같은 워크플로를 계속 교정하고 있다면, 그것은 스킬이 돼야 합니다. best-practices

20.1플러그인이 담는 것

공식플러그인은 능력을 재사용 가능한 워크플로로 묶습니다. ChatGPT와 코덱스가 하나의 범용 플러그인 디렉터리를 공유하므로, 같은 공개 플러그인이 양쪽 표면에서 발견됩니다. plugins

20.2찾기와 설치

공식CLI에서는 /plugins로 브라우저를 엽니다. 설정된 마켓플레이스에서 설치한 뒤, 번들된 스킬이나 도구를 쓰려면 새 세션을 시작해야 합니다. plugins

CLI에서 관리

codex plugin list
codex plugin add <이름>
codex plugin remove <이름>

# 마켓플레이스 소스 관리
codex plugin marketplace add owner/repo
codex plugin marketplace list

공식마켓플레이스 추가는 GitHub 축약형(owner/repo 또는 owner/repo@ref), HTTP·HTTPS git URL, SSH git URL, 로컬 마켓플레이스 루트 디렉터리를 받습니다. --ref로 git ref를 고정하고, --sparse PATH를 반복해 sparse 체크아웃을 씁니다. developer-commands

공식모든 플러그인 명령에 --json을 붙이면 자동화용 출력이 나옵니다. 예를 들어 codex plugin list --json은 installed와 available 배열을 내고, 각 항목에 pluginId·version·enabled·installPolicy·authPolicy가 들어갑니다. developer-commands

공식API 키로 로그인한 경우에도 OpenAI가 선별한 플러그인은 쓸 수 있습니다. 다만 연결 흐름이 지원되지 않는 OAuth 기능을 요구하는 일부 플러그인은 쓸 수 없습니다. auth

20.3직접 만들기

공식스킬이 저작 형식이고 플러그인이 설치 가능한 배포 단위입니다. 재사용 스킬을 배포하고 싶거나, 스킬 둘 이상을 묶고 싶거나, 커넥터와 함께 배포하고 싶을 때 플러그인으로 포장합니다. build-skills build-plugins

공식스킬이 MCP에 의존한다면 그 의존성을 agents/openai.yaml에 선언합니다. 그러면 코덱스가 설치와 배선을 자동으로 처리할 수 있습니다. customization/overview

공식플러그인은 생애주기 훅도 담을 수 있습니다. 기본 위치는 플러그인 루트의 hooks/hooks.json이고, 매니페스트(.codex-plugin/plugin.json)의 hooks 항목으로 바꿀 수 있습니다. 매니페스트 경로는 플러그인 루트 기준으로 해석되고 루트 밖으로 나갈 수 없습니다. hooks

.codex-plugin/plugin.json

{
  "name": "repo-policy",
  "hooks": "./hooks/hooks.json"
}

20.4배포와 검수

공식플러그인 훅 명령은 환경 변수 몇 개를 받습니다. PLUGIN_ROOT는 설치된 플러그인 루트, PLUGIN_DATA는 쓰기 가능한 데이터 디렉터리를 가리킵니다. 기존 플러그인 훅과의 호환을 위해 CLAUDE_PLUGIN_ROOT와 CLAUDE_PLUGIN_DATA도 함께 설정됩니다. hooks

21.1MCP가 무엇을 해결하나

공식MCP(Model Context Protocol)는 모델을 도구와 맥락에 연결하는 표준입니다. 코덱스에 서드파티 문서 접근을 주거나, 브라우저·Figma 같은 개발 도구와 상호작용하게 합니다. extend/mcp

근거는 커스터마이징 문서와 MCP 문서입니다. customization/overview extend/mcp

공식언제 쓰는지 기준이 넷으로 정리돼 있습니다. 필요한 맥락이 저장소 밖에 있을 때, 데이터가 자주 바뀔 때, 붙여 넣은 지시가 아니라 도구를 쓰게 하고 싶을 때, 여러 사용자·프로젝트에 반복 가능한 통합이 필요할 때. best-practices

21.2서버 붙이기

공식MCP 설정은 다른 코덱스 설정과 함께 config.toml에 저장됩니다. 기본은 ~/.codex/config.toml이고, 프로젝트 범위로 묶으려면 .codex/config.toml을 씁니다(신뢰된 프로젝트만). 데스크톱 앱·CLI·IDE 확장이 이 설정을 공유하므로 한 번 설정하면 표면을 옮겨도 다시 하지 않아도 됩니다. extend/mcp

CLI에서 추가

# 예: Context7 (개발자 문서용 무료 MCP 서버)
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 설정된 서버 목록 / 전체 명령
codex mcp list
codex mcp --help

# OAuth 를 지원하는 서버 로그인
codex mcp login <서버이름>

공식지원되는 서버 형태는 둘입니다. STDIO 서버는 명령으로 시작되는 로컬 프로세스이고 환경 변수를 받습니다. Streamable HTTP 서버는 주소로 접근하며 베어러 토큰 인증, OAuth 인증, 신뢰된 퍼스트파티 서버에 대한 ChatGPT 세션 인증을 지원합니다. extend/mcp

config.toml (STDIO 서버 주요 키)

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["LOCAL_TOKEN"]

공식코덱스는 초기화 때 서버가 돌려주는 instructions 필드를 읽어 그 서버 전체에 적용되는 안내로 씁니다. 서버를 만드는 쪽이라면 도구를 가로지르는 워크플로·제약·요율 제한을 여기 담고, 처음 512자가 자기완결적이도록 씁니다. 코덱스가 그 서버를 어떻게 쓸지 판단하는 시점에 그 부분이 먼저 읽히기 때문입니다. extend/mcp

지금 붙어 있는 서버 보기 (TUI)

/mcp

21.3인증과 승인

공식데스크톱 앱과 IDE 확장의 서버 목록은 어느 서버가 켜져 있고 어느 서버가 OAuth를 요구하는지 보여 줍니다. OAuth 서버는 Authenticate를 눌러 로그인합니다. extend/mcp

공식MCP 도구 호출도 승인 대상입니다. 부수효과를 알리는 도구는 승인을 요청할 수 있고, 파괴적 주석을 단 도구 호출은 다른 힌트를 함께 달고 있어도 항상 승인이 필요합니다. agent-approvals-security

21.4스킬과 함께 쓰기

공식실무에서 MCP는 스킬과 짝지을 때 가장 쓸모가 큽니다. 스킬이 워크플로를 정의하고 어떤 MCP 도구를 쓸지 지목합니다. 스킬이 MCP에 의존하면 그 의존성을 agents/openai.yaml에 선언해 코덱스가 설치와 배선을 자동으로 하게 합니다. customization/overview

21.5무엇을 붙이면 실제로 이득인가

공식공식 권고는 절제입니다. 실제 워크플로를 열어 주는 것만 붙입니다. 쓰는 도구를 전부 배선하며 시작하지 말고, 자주 하는 수동 루프를 확실히 없애는 한두 개로 시작한 뒤 늘립니다. best-practices

공식절제의 이유가 비용에도 있습니다. 공식 요금 문서는 한도를 오래 쓰는 방법으로 "쓰는 MCP 서버 수를 제한하라"를 명시합니다. 서버마다 메시지에 맥락이 더해지고 그만큼 한도를 씁니다. 안 쓸 때는 끕니다. pricing

22.1훅이 발동하는 시점

공식훅은 자기 스크립트를 에이전트 루프에 끼워 넣는 확장 프레임워크입니다. 문서가 드는 쓰임은 채팅을 자체 로깅·분석 엔진으로 보내기, 팀 프롬프트를 검사해 API 키 붙여넣기 차단, 채팅을 요약해 지속 메모리 만들기, 턴이 끝날 때 검증 검사로 표준 강제, 특정 디렉터리에서 프롬프트 커스터마이징입니다. hooks

공식런타임 동작 셋을 알아 둡니다. 여러 파일의 매칭 훅이 전부 돕니다. 같은 이벤트의 여러 명령 훅은 동시에 시작되므로 한 훅이 다른 훅의 시작을 막을 수 없습니다. 관리형이 아닌 명령 훅은 실행 전에 검토·신뢰를 거쳐야 합니다. hooks

22.2설정 위치와 형식

공식코덱스는 활성 설정 계층 옆에서 훅을 찾습니다. hooks.json 파일이거나 config.toml 안의 [hooks] 인라인 테이블입니다. 실무에서 유용한 위치는 넷입니다. hooks

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <프로젝트>/.codex/hooks.json
• <프로젝트>/.codex/config.toml

공식훅 소스가 여럿이면 매칭되는 훅을 전부 로드합니다. 우선순위가 높은 설정 계층이 낮은 계층의 훅을 대체하지 않습니다. 한 계층에 hooks.json과 인라인 [hooks]가 둘 다 있으면 병합하고 시작할 때 경고합니다. 계층당 하나의 표현만 쓰는 편이 낫습니다. hooks

공식프로젝트 로컬 훅은 그 프로젝트의 .codex/ 계층이 신뢰될 때만 로드됩니다. 신뢰하지 않는 프로젝트에서도 사용자·시스템 훅은 각자의 계층에서 그대로 로드됩니다. hooks

공식구조는 세 층입니다. 이벤트 → 매처 그룹 → 핸들러. hooks

~/.codex/hooks.json

{
  "description": "Optional lifecycle hooks for this workspace.",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes",
            "additionalContextLimit": 5000
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ]
  }
}

공식matcher는 정규식 문자열이고, "*"·""이거나 아예 없으면 그 이벤트의 모든 발생에 매칭됩니다. 다만 모든 이벤트가 매처를 존중하지는 않습니다. hooks

공식apply_patch는 매처 값으로 Edit나 Write도 받습니다. 웹 검색 같은 호스티드 도구는 로컬 함수 도구 훅 경로를 쓰지 않으므로 훅이 붙지 않습니다. 문서는 도구 훅을 유용한 가드레일이지 완전한 강제 경계는 아니라고 명시합니다. hooks

22.3입출력과 차단

공식모든 명령 훅은 stdin으로 JSON 객체 하나를 받습니다. 공통 필드는 session_id, transcript_path, cwd, hook_event_name, model입니다. 여러 이벤트가 permission_mode도 함께 넘깁니다. hooks

공식출력 계약은 이렇습니다. 출력 없이 종료 코드 0이면 성공으로 보고 계속합니다. JSON을 내면 공통 출력 필드를 씁니다. hooks

훅 표준 출력 (JSON)

{
  "continue": true,
  "stopReason": "optional",
  "systemMessage": "optional",
  "suppressOutput": false
}

공식모델이 보는 훅 출력 메시지는 기본적으로 약 2,500토큰으로 제한됩니다. 넘치면 코덱스가 전문을 <세션>/hook_outputs/ 아래에 저장하고 모델에는 앞뒤 미리보기와 파일 경로를 줍니다. 이것을 spilling이라 부릅니다. hooks

공식한도는 핸들러의 additionalContextLimit으로 조정합니다. 생략하면 기본 2,500이고, 양의 정수로 바꾸거나 0으로 전체를 그대로 넘길 수 있습니다. 다만 문서는 0을 피하라고 경고합니다. 훅이 엄격한 출력 상한을 스스로 지키지 않으면 훅 하나가 컨텍스트 윈도우를 통째로 먹을 수 있습니다. hooks

22.4실전 훅 5종

공식 문서가 드는 쓰임을 실제 배선으로 옮기면 이렇게 갈립니다.

공식차단 목적이라면 훅보다 규칙(L2 14.3)이 맞습니다. 공식 문서가 도구 훅을 유용한 가드레일이지 완전한 강제 경계는 아니라고 명시하고, 훅의 차단은 이벤트마다 지원 여부가 갈리며 PreToolUse에서는 아예 지원되지 않습니다. 훅은 관찰·주입·검증에, 규칙은 허용·차단에 씁니다. hooks

22.5훅 디버깅

공식코덱스는 어떤 훅이 돌 수 있는지 정하기 전에 설정된 훅을 나열합니다. 관리형이 아닌 명령 훅은 정확한 훅 정의를 검토하고 신뢰해야 돕니다. 신뢰는 그 훅의 현재 해시에 기록되므로, 새 훅이나 바뀐 훅은 검토 대상으로 표시되고 신뢰하기 전까지 건너뛰어집니다. hooks

CLI에서

/hooks

공식/hooks로 훅 소스를 보고, 새 훅이나 바뀐 훅을 검토·신뢰하고, 관리형이 아닌 훅을 개별로 끕니다. 시작 시 검토가 필요한 훅이 있으면 코덱스가 경고를 찍어 /hooks를 열라고 알려 줍니다. hooks

공식훅 소스를 코덱스 밖에서 이미 검증한 일회성 자동화라면 --dangerously-bypass-hook-trust로 그 실행에 한해 신뢰 없이 돌릴 수 있습니다. hooks

공식훅을 통째로 끄려면 설정에서 기능을 내립니다. hooks가 정식 키이고 codex_hooks는 폐기된 별칭입니다. hooks

config.toml

[features]
hooks = false

22.6규칙을 문서가 아니라 훅으로

관행문서에 적힌 규칙과 훅으로 배선된 규칙은 구속력이 다릅니다. 문서 규칙은 모델이 기억해야 발화하고, 훅은 이벤트가 나면 무조건 돕니다. 같은 규칙이 세 번 이상 무시되면 그것은 문서가 아니라 배선의 문제입니다.

공식다만 반대 함정도 있습니다. 돌지 않을 기계를 새로 짓는 것입니다. 훅을 만들기 전에 물을 것은 하나입니다. 이 검사가 이미 CI나 pre-commit에 있는가. 있으면 훅을 더하지 않고 그쪽을 고칩니다. 공식 문서도 지침을 인프라(pre-commit 훅·린터·타입 체커)와 짝지으라고 권합니다. customization/overview

23.1위임이 이득인 이유

공식컨텍스트 윈도우가 커도 모델에는 한계가 있습니다. 요구사항·제약·결정을 정의하는 메인 채팅에 탐색 메모, 테스트 로그, 스택 트레이스, 명령 출력 같은 잡음이 쏟아지면 세션의 신뢰도가 시간에 따라 떨어집니다. 문서는 이것을 컨텍스트 오염(유용한 정보가 잡음에 묻힘)과 컨텍스트 부패(덜 관련된 세부로 채워지며 성능 저하)로 부릅니다. agent-configuration/subagents

공식서브에이전트는 잡음을 메인 스레드 밖으로 옮깁니다. 메인 에이전트는 요구사항·결정·최종 산출물에 집중하고, 전문화된 서브에이전트가 탐색·테스트·로그 분석을 병렬로 돌고, 원시 중간 출력 대신 요약을 돌려줍니다. agent-configuration/subagents

공식시작점으로는 읽기 중심 작업(탐색·테스트·트리아지·요약)에 병렬 에이전트를 씁니다. 쓰기 중심 병렬은 조심합니다. 여러 에이전트가 동시에 코드를 고치면 충돌이 나고 조율 비용이 커집니다. agent-configuration/subagents

23.2커스텀 에이전트 정의

공식코덱스에는 내장 에이전트 셋이 있습니다. default(범용 폴백), worker(구현·수정 중심), explorer(읽기 중심 코드베이스 탐색). agent-configuration/subagents

공식직접 정의하려면 ~/.codex/agents/(개인) 또는 .codex/agents/(프로젝트)에 독립 TOML 파일을 둡니다. 파일 하나가 에이전트 하나입니다. 필수 필드는 name·description·developer_instructions 셋입니다. 이름이 내장 에이전트와 겹치면 커스텀 쪽이 이깁니다. agent-configuration/subagents

.codex/agents/pr-explorer.toml

name = "pr_explorer"
description = "Read-only codebase explorer for gathering evidence before changes are proposed."
model = "gpt-5.3-codex-spark"
developer_instructions = """
Gather evidence only. Do not propose or apply changes.
Return file paths and line ranges with a one-line justification each.
"""

공식커스텀 에이전트 파일은 스폰되는 세션의 설정 계층으로 로드되므로, 일반 세션 설정과 같은 키를 덮어쓸 수 있습니다(model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config 등). 파일이 생략한 설정은 부모에서 상속합니다. agent-configuration/subagents

공식전역 설정은 [agents]에 둡니다. agent-configuration/subagents

23.3위임 지시 설계

공식좋은 서브에이전트 프롬프트는 셋을 설명합니다. 작업을 어떻게 나눌지, 모두 끝날 때까지 기다릴지, 어떤 요약이나 출력을 돌려줄지. agent-configuration/subagents

공식 문서의 예시 프롬프트

I would like to review the following points on the current PR (this branch vs main).
Spawn one agent per point, wait for all of them, and summarize the result for each point.
1. Security issue
2. Code quality
3. Bugs
4. Race
5. Test flakiness
6. Maintainability of the code

공식CLI에서는 /agent로 활성 에이전트 스레드를 오가며 진행 중인 스레드를 확인합니다. 여러 에이전트가 돌면 코덱스는 요청된 결과가 전부 준비될 때까지 기다린 뒤 통합 응답을 돌려줍니다. agent-configuration/subagents

공식권한은 상속됩니다. 서브에이전트는 부모 턴에서 선택된 승인 모드와 샌드박스 정책을 물려받으므로, 위임을 시키기 전에 부모 턴의 권한을 정합니다. 세션 중에 /permissions로 바꾼 런타임 덮어쓰기도 자식에 다시 적용됩니다. 커스텀 에이전트 파일이 다른 기본값을 적어 두었더라도 그렇습니다. agent-configuration/subagents

공식대화형 CLI에서는 메인 스레드를 보고 있어도 비활성 에이전트 스레드에서 승인 요청이 뜰 수 있습니다. 승인 오버레이가 출처 스레드 라벨을 보여 주고, o를 눌러 그 스레드를 열어 본 뒤 승인·거절·답변할 수 있습니다. 비대화 흐름에서는 새 승인이 필요한 동작이 실패하고 오류가 부모 워크플로로 올라갑니다. agent-configuration/subagents

23.4위임하면 안 되는 일

관행위임의 대가는 맥락 단절입니다. 서브에이전트는 요약을 돌려주므로, 판단에 필요한 근거가 요약에서 빠지면 메인 에이전트가 잘못된 결론으로 갑니다. 그래서 다음은 위임하지 않는 편이 낫습니다.

• 결정 자체(무엇을 만들지, 어느 접근을 고를지). 서브에이전트에게는 근거 수집을 시키고 결정은 메인에서 합니다.
• 같은 파일을 여러 에이전트가 동시에 고치는 작업. 충돌과 조율 비용이 이득을 넘습니다.
• 한 번에 끝나는 짧은 작업. 스폰 비용이 더 큽니다.

공식쓰기 중심 병렬을 조심하라는 것은 공식 문서의 권고이기도 합니다. 파일 충돌을 구조로 막는 방법(워크트리)은 L4 27장에서 다룹니다. agent-configuration/subagents

24.1한 번 보여주고 스킬로 굳히기

공식워크플로를 말로 설명하기보다 보여 주는 편이 쉬울 때, 기록과 재생(Record & Replay)이 그 시연을 잡아 단계를 분석하고 재사용 가능한 스킬 초안을 만듭니다. extend/record-and-replay build-skills

관행이 경로가 값을 하는 곳은 UI가 개입하는 절차입니다. 관리자 콘솔에서 설정 몇 개를 바꾸고 결과를 확인하는 일 같은 것은 글로 적으면 길고 부정확한데, 한 번 보여 주면 그대로 남습니다.

24.2컴퓨터 조작

공식컴퓨터 조작은 작업 중에 데스크톱 앱을 쓰게 하는 기능입니다. computer-use

공식승인 관점에서 알아 둘 것이 하나 있습니다. 컴퓨터 조작이 새 웹사이트나 도메인에 접근하는 것은 승인 대상이고, 자동 검토가 켜져 있으면 그 요청이 검토 에이전트로 갑니다. sandboxing/auto-review

24.3브라우저

공식브라우저는 웹을 조사하고 웹사이트와 상호작용하게 하는 기능입니다. browser

24.4크롬 확장

공식크롬 확장은 ChatGPT와 함께 크롬을 쓰면서 브라우저 권한·웹사이트 승인·브라우징 데이터를 관리하게 합니다. chrome-extension

관행내장 브라우저와 크롬 확장의 갈림은 로그인 세션이 필요한가입니다. 이미 로그인된 상태로만 볼 수 있는 페이지를 다뤄야 하면 확장 쪽이고, 공개 페이지 조사라면 내장 브라우저로 충분합니다.

24.5맥 앱 맥락 주기

공식Appshots는 맥의 어떤 앱에서든 ChatGPT에 맥락을 주는 기능입니다. appshots

화면 맥락을 지속적으로 메모리로 만드는 크로니클과는 다릅니다. 크로니클은 L2 13.6에 있고, 켜기 전에 확인할 대가가 따로 있습니다.

24.6검증 루프로 묶기

관행화면 계열 확장의 실질적 값은 "코덱스가 브라우저를 쓸 수 있다"가 아니라 자기 변경을 스스로 확인하게 만드는 것입니다. 프런트엔드 수정을 시킬 때 완료 조건에 "브라우저에서 해당 화면을 열어 콘솔 오류가 없고 모바일 폭에서 가로 넘침이 없음을 확인"을 넣으면, 고쳤다는 주장이 검증된 상태로 돌아옵니다. 쿡북의 실행 계획 규격은 이것을 선택 사항으로 두지 않습니다. "검증은 선택이 아니다"라고 못박고 수용 기준을 사람이 확인할 수 있는 행동으로 쓰라고 요구합니다. cookbook codex_exec_plans

공식이것은 공식 베스트 프랙티스의 확장이기도 합니다. 변경 요청에서 멈추지 말고 테스트를 만들게 하고, 검사를 돌리게 하고, 결과를 확인하게 한 뒤 받아들이라는 것입니다. 무엇이 "잘된 것"인지는 프롬프트나 AGENTS.md가 알려 줘야 합니다. best-practices

25.1터미널 다듬기

공식CLI 커스터마이징은 구문 강조, 테마, 셸 동작, 자동완성, 편집기 연동을 다룹니다. cli-customization

셸 자동완성 생성

codex completion zsh > "${fpath[1]}/_codex"

공식세션 안에서 바꾸는 것들은 슬래시 명령입니다. /theme로 구문 강조 테마, /statusline으로 하단 상태줄 항목(모델·컨텍스트·한도·git·토큰·세션)을 고르고 순서를 정하고 config.toml에 저장합니다. /title은 터미널 창 제목 항목(프로젝트·상태·스레드·브랜치·모델·진행)을 같은 방식으로 정합니다. developer-commands

공식긴 프롬프트는 VISUAL이나 EDITOR로 설정된 편집기에서 엽니다. 단축키가 손에 안 맞으면 /keymap으로 재정의합니다. codex/cli developer-commands

config.toml (키맵 예)

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

공식컴포저의 일부 동작은 대응하는 tui.keymap.global 바인딩으로 폴백하고, 맥락별 바인딩이 지원되면 그쪽이 우선합니다. 빈 목록은 그 동작의 바인딩을 해제합니다. config-file/config-basic

25.2IDE 확장 설정

공식IDE 확장 설정 전량은 별도 레퍼런스가 정본입니다. 이 편과 관련해 자주 쓰이는 것 둘은 리뷰 전달 방식(chatgpt.reviewDelivery)과 윈도우에서 에이전트를 WSL2 안에 유지하는 설정입니다. developer-settings

VS Code settings.json

{
  "chatgpt.reviewDelivery": "detached",
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

후자의 근거와 의미는 L2 15.4에 있습니다. agent-approvals-security

25.3데스크톱 앱 설정

공식데스크톱 앱 설정과 명령·단축키도 각각 레퍼런스가 있습니다. reference/settings reference/commands

공식윈도우에서는 기본 편집기(Open 대상)와 통합 터미널(PowerShell·명령 프롬프트·Git Bash·WSL)을 각각 고릅니다. 편집기는 프로젝트별로 덮어쓸 수 있고, 이미 프로젝트에서 다른 앱을 골랐다면 그 선택이 우선합니다. 터미널 변경은 새 터미널 세션부터 적용됩니다. windows/windows-app

25.4지휘소 화면

공식Codex Micro는 코덱스 채팅의 지휘소 역할을 하는 화면입니다. features/codex-micro

공식여러 채팅을 동시에 굴릴 때 상태를 따라가는 다른 수단은 데스크톱 앱의 Activity 뷰입니다. 사이드바의 벨에서 읽지 않음·실행 중·응답 대기 채팅을 모아 봅니다. notifications