명령줄 옵션
출처 URL: https://developers.openai.com/codex/cli/reference
명령줄 옵션
섹션 제목: “명령줄 옵션”export const globalFlagOptions = [
{
key: “PROMPT”,
type: “string”,
description:
“Optional text instruction to start the session. Omit to launch the TUI without a pre-filled message.”,
},
{
key: “—image, -i”,
type: “path[,path…]”,
description:
“Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.”,
},
{
key: “—model, -m”,
type: “string”,
description:
“Override the model set in configuration (for example gpt-5-codex).”,
},
{
key: “—oss”,
type: “boolean”,
defaultValue: “false”,
description:
‘Use the local open source model provider (equivalent to -c model_provider="oss"). Validates that Ollama is running.’,
},
{
key: “—profile, -p”,
type: “string”,
description:
“Configuration profile name to load from ~/.codex/config.toml.”,
},
{
key: “—sandbox, -s”,
type: “read-only | workspace-write | danger-full-access”,
description:
“Select the sandbox policy for model-generated shell commands.”,
},
{
key: “—ask-for-approval, -a”,
type: “untrusted | on-request | never”,
description:
“Control when Codex pauses for human approval before running a command. on-failure is deprecated; prefer on-request for interactive runs or never for non-interactive runs.”,
},
{
key: “—full-auto”,
type: “boolean”,
defaultValue: “false”,
description:
“Shortcut for low-friction local work: sets --ask-for-approval on-request and --sandbox workspace-write.”,
},
{
key: “—dangerously-bypass-approvals-and-sandbox, —yolo”,
type: “boolean”,
defaultValue: “false”,
description:
“Run every command without approvals or sandboxing. Only use inside an externally hardened environment.”,
},
{
key: “—cd, -C”,
type: “path”,
description:
“Set the working directory for the agent before it starts processing your request.”,
},
{
key: “—search”,
type: “boolean”,
defaultValue: “false”,
description:
‘Enable live web search (sets web_search = "live" instead of the default "cached").’,
},
{
key: “—add-dir”,
type: “path”,
description:
“Grant additional directories write access alongside the main workspace. Repeat for multiple paths.”,
},
{
key: “—no-alt-screen”,
type: “boolean”,
defaultValue: “false”,
description:
“Disable alternate screen mode for the TUI (overrides tui.alternate_screen for this run).”,
},
{
key: “—enable”,
type: “feature”,
description:
“Force-enable a feature flag (translates to -c features.<name>=true). Repeatable.”,
},
{
key: “—disable”,
type: “feature”,
description:
“Force-disable a feature flag (translates to -c features.<name>=false). Repeatable.”,
},
{
key: “—config, -c”,
type: “key=value”,
description:
“Override configuration values. Values parse as JSON if possible; otherwise the literal string is used.”,
},
];
export const commandOverview = [
{
key: “codex”,
href: “/codex/cli/reference#codex-interactive”,
type: “stable”,
description:
“Launch the terminal UI. Accepts the global flags above plus an optional prompt or image attachments.”,
},
{
key: “codex app-server”,
href: “/codex/cli/reference#codex-app-server”,
type: “experimental”,
description:
“Launch the Codex app server for local development or debugging.”,
},
{
key: “codex app”,
href: “/codex/cli/reference#codex-app”,
type: “stable”,
description:
“Launch the Codex desktop app on macOS, optionally opening a specific workspace path.”,
},
{
key: “codex debug app-server send-message-v2”,
href: “/codex/cli/reference#codex-debug-app-server-send-message-v2”,
type: “experimental”,
description:
“Debug app-server by sending a single V2 message through the built-in test client.”,
},
{
key: “codex apply”,
href: “/codex/cli/reference#codex-apply”,
type: “stable”,
description:
“Apply the latest diff generated by a Codex Cloud task to your local working tree. Alias: codex a.”,
},
{
key: “codex cloud”,
href: “/codex/cli/reference#codex-cloud”,
type: “experimental”,
description:
“Browse or execute Codex Cloud tasks from the terminal without opening the TUI. Alias: codex cloud-tasks.”,
},
{
key: “codex completion”,
href: “/codex/cli/reference#codex-completion”,
type: “stable”,
description:
“Generate shell completion scripts for Bash, Zsh, Fish, or PowerShell.”,
},
{
key: “codex features”,
href: “/codex/cli/reference#codex-features”,
type: “stable”,
description:
“List feature flags and persistently enable or disable them in config.toml.”,
},
{
key: “codex exec”,
href: “/codex/cli/reference#codex-exec”,
type: “stable”,
description:
“Run Codex non-interactively. Alias: codex e. Stream results to stdout or JSONL and optionally resume previous sessions.”,
},
{
key: “codex execpolicy”,
href: “/codex/cli/reference#codex-execpolicy”,
type: “experimental”,
description:
“Evaluate execpolicy rule files and see whether a command would be allowed, prompted, or blocked.”,
},
{
key: “codex login”,
href: “/codex/cli/reference#codex-login”,
type: “stable”,
description:
“Authenticate Codex using ChatGPT OAuth, device auth, or an API key piped over stdin.”,
},
{
key: “codex logout”,
href: “/codex/cli/reference#codex-logout”,
type: “stable”,
description: “Remove stored authentication credentials.”,
},
{
key: “codex mcp”,
href: “/codex/cli/reference#codex-mcp”,
type: “experimental”,
description:
“Manage Model Context Protocol servers (list, add, remove, authenticate).”,
},
{
key: “codex mcp-server”,
href: “/codex/cli/reference#codex-mcp-server”,
type: “experimental”,
description:
“Run Codex itself as an MCP server over stdio. Useful when another agent consumes Codex.”,
},
{
key: “codex resume”,
href: “/codex/cli/reference#codex-resume”,
type: “stable”,
description:
“Continue a previous interactive session by ID or resume the most recent conversation.”,
},
{
key: “codex fork”,
href: “/codex/cli/reference#codex-fork”,
type: “stable”,
description:
“Fork a previous interactive session into a new thread, preserving the original transcript.”,
},
{
key: “codex sandbox”,
href: “/codex/cli/reference#codex-sandbox”,
type: “experimental”,
description:
“Run arbitrary commands inside Codex-provided macOS seatbelt or Linux sandboxes (Landlock by default, optional bubblewrap pipeline).”,
},
];
export const execOptions = [
{
key: “PROMPT”,
type: “string | - (read stdin)”,
description:
“Initial instruction for the task. Use - to pipe the prompt from stdin.”,
},
{
key: “—image, -i”,
type: “path[,path…]”,
description:
“Attach images to the first message. Repeatable; supports comma-separated lists.”,
},
{
key: “—model, -m”,
type: “string”,
description: “Override the configured model for this run.”,
},
{
key: “—oss”,
type: “boolean”,
defaultValue: “false”,
description:
“Use the local open source provider (requires a running Olaanng”).
type: “codex 기능 비활성화 config.toml에서 기능 플래그를 영구적으로 비활성화합니다. 제공된 경우 활성 --profile을 존중합니다.”,
},
];
export const execResumeOptions = [
{
key: “SESSION_ID”,
type: “uuid”,
description:
“지정한 세션을 이어서 실행합니다. 생략하면 --last를 사용해 가장 최근 세션을 계속합니다.”,
},
{
key: “—last”,
type: “boolean”,
defaultValue: “false”,
description:
“현재 작업 디렉터리에서 가장 최근 대화를 이어서 실행합니다.”,
},
{
key: “—all”,
type: “boolean”,
defaultValue: “false”,
description:
“현재 작업 디렉터리 외부의 세션도 포함하여 가장 최근 세션을 선택합니다.”,
},
{
key: “—image, -i”,
type: “path[,path…]”,
description:
“후속 프롬프트에 하나 이상의 이미지를 첨부합니다. 여러 경로는 쉼표로 구분하거나 플래그를 반복해서 사용합니다.”,
},
{
key: “PROMPT”,
type: “string | - (read stdin)”,
description:
“이어서 실행하자마자 전송될 선택적 후속 지시입니다.”,
},
];
export const forkOptions = [
{
key: “SESSION_ID”,
type: “uuid”,
description:
“지정한 세션을 포크합니다. 생략하면 --last를 사용해 가장 최근 세션을 포크합니다.”,
},
{
key: “—last”,
type: “boolean”,
defaultValue: “false”,
description:
“선택기를 건너뛰고 자동으로 가장 최근 대화를 포크합니다.”,
},
{
key: “—all”,
type: “boolean”,
defaultValue: “false”,
description:
“선택기에 현재 작업 디렉터리 외부의 세션도 표시합니다.”,
},
];
export const execpolicyOptions = [ { key: “—rules, -r”, type: “path (repeatable)”, description: “평가할 execpolicy 규칙 파일 경로입니다. 여러 플래그를 제공해 파일 간 규칙을 결합합니다.”, }, { key: “—pretty”, type: “boolean”, defaultValue: “false”, description: “JSON 결과를 보기 좋게 출력합니다.”, }, { key: “COMMAND…”, type: “var-args”, description: “지정한 정책에 대해 확인할 명령입니다.”, }, ];
export const loginOptions = [
{
key: “—with-api-key”,
type: “boolean”,
description:
“stdin에서 API 키를 읽어옵니다(예: printenv OPENAI_API_KEY | codex login --with-api-key).”,
},
{
key: “—device-auth”,
type: “boolean”,
description:
“브라우저 창을 여는 대신 OAuth 장치 코드 흐름을 사용합니다.”,
},
{
key: “status subcommand”,
type: “codex login status”,
description:
“활성 인증 모드를 출력하고 로그인되어 있으면 0으로 종료합니다.”,
},
];
export const applyOptions = [ { key: “TASK_ID”, type: “string”, description: “변경 사항을 적용할 Codex Cloud 작업의 식별자입니다.”, }, ];
export const sandboxMacOptions = [
{
key: “—full-auto”,
type: “boolean”,
defaultValue: “false”,
description:
“승인 없이 현재 작업 공간과 /tmp에 쓰기 권한을 부여합니다.”,
},
{
key: “—config, -c”,
type: “key=value”,
description:
“샌드박스 실행에 구성 재정의를 전달합니다(반복 가능).”,
},
{
key: “COMMAND…”,
type: “var-args”,
description:
“macOS Seatbelt 하에서 실행할 셸 명령입니다. -- 이후의 모든 내용이 전달됩니다.”,
},
];
export const sandboxLinuxOptions = [
{
key: “—full-auto”,
type: “boolean”,
defaultValue: “false”,
description:
“Landlock 샌드박스 내부에서 현재 작업 공간과 /tmp에 쓰기 권한을 부여합니다.”,
},
{
key: “—config, -c”,
type: “key=value”,
description:
“샌드박스를 시작하기 전에 적용할 구성 재정의입니다(반복 가능).”,
},
{
key: “COMMAND…”,
type: “var-args”,
description:
“Landlock + seccomp 하에서 실행할 명령입니다. -- 이후에 실행 파일을 제공합니다.”,
},
];
export const completionOptions = [ { key: “SHELL”, type: “bash | zsh | fish | power-shell | elvish”, defaultValue: “bash”, description: “완성 스크립트를 생성할 셸입니다. 출력은 stdout으로 나옵니다.”, }, ];
export const cloudExecOptions = [
{
key: “QUERY”,
type: “string”,
description:
“작업 프롬프트입니다. 생략하면 Codex가 상세 정보를 대화형으로 묻습니다.”,
},
{
key: “—env”,
type: “ENV_ID”,
description:
“대상 Codex Cloud 환경 식별자(필수). codex cloud로 옵션을 나열하세요.”,
},
{
key: “—attempts”,
type: “1-4”,
defaultValue: “1”,
description:
“Codex Cloud가 실행할 어시스턴트 시도 횟수(최고-N)입니다.”,
},
];
export const cloudListOptions = [ { key: “—env”, type: “ENV_ID”, description: “환경 식별자로 작업을 필터링합니다.”, }, { key: “—limit”, type: “1-20”, defaultValue: “20”, description: “반환할 작업의 최대 개수입니다.”, }, { key: “—cursor”, type: “string”, description: “이전 요청에서 반환된 페이지네이션 커서입니다.”, }, { key: “—json”, type: “boolean”, defaultValue: “false”, description: “일반 텍스트 대신 기계 판독 가능한 JSON을 출력합니다.”, }, ];
export const mcpCommands = [
{
key: “list”,
type: “—json”,
description:
“설정된 MCP 서버 목록을 출력합니다. 기계 판독 출력을 원하면 --json을 추가하세요.”,
},
{
key: “get --json은 원본 구성 항목을 출력합니다.”,
},
{
key: “add --env KEY=VALUE를 지원합니다.”,
},
{
key: “remove
export const mcpAddOptions = [
{
key: “COMMAND…”,
type: “stdio transport”,
description:
“MCP 서버를 실행할 실행 파일과 인수입니다. -- 이후에 제공합니다.”,
},
{
key: “—env KEY=VALUE”,
type: “repeatable”,
description:
“stdio 서버를 실행할 때 적용할 환경 변수 할당입니다.”,
},
{
key: “—url”,
type: “https://…”,
description:
“stdio 대신 스트리밍 가능한 HTTP 서버를 등록합니다. COMMAND...와 상호 배타적입니다.”,
},
{
key: “—bearer-token-env-var”,
type: “ENV_VAR”,
description:
“스트리밍 가능한 HTTP 서버에 연결할 때 베어러 토큰으로 보낼 환경 변수입니다.”,
},
];
이 참고서를 읽는 방법
섹션 제목: “이 참고서를 읽는 방법”이 페이지는 문서화된 모든 Codex CLI 명령과 플래그를 목록화합니다. 상호작용 테이블을 사용해 키나 설명으로 검색하세요. 각 섹션에서는 옵션이 안정적(stable)인지 실험적(experimental)인지 표시하며, 위험한 조합도 알려줍니다.
CLI는 대부분의 기본값을 <code>~/.codex/config.toml</code>에서 상속합니다. 커맨드라인에서 전달한 <code>-c key=value</code> 재정의는 해당 호출에서 우선 적용됩니다. 자세한 내용은 구성 기초를 참조하세요.
전역 플래그
섹션 제목: “전역 플래그”<ConfigTable client:load options={globalFlagOptions} />이 옵션들은 기본 codex 명령에 적용되며 아래 섹션에 별도 명시가 없는 한 각 하위 명령에도 전파됩니다. 하위 명령을 실행할 때는 전역 플래그를 그 뒤에 위치시키세요(예: codex exec --oss ...). 이렇게 해야 Codex가 의도한 대로 적용합니다.
명령 개요
섹션 제목: “명령 개요”Maturity 열은 Experimental, Beta, Stable 등의 기능 성숙도 레이블을 사용합니다. 이러한 레이블의 해석 방법은 기능 성숙도를 참조하세요.
<ConfigTable client:load options={commandOverview} secondColumnTitle="Maturity" secondColumnVariant="maturity"/>명령 세부 정보
섹션 제목: “명령 세부 정보”codex (대화형)
섹션 제목: “codex (대화형)”하위 명령 없이 codex를 실행하면 대화형 터미널 UI(TUI)가 시작됩니다. 에이전트는 위에 있는 전역 플래그와 이미지 첨부를 모두 받습니다. 웹 검색은 기본적으로 캐시 모드이며 --search를 사용해 실시간 브라우징으로 전환하고 --full-auto를 사용하면 Codex가 대부분의 명령을 프롬프트 없이 실행합니다.
codex app-server
섹션 제목: “codex app-server”Codex 앱 서버를 로컬에서 시작합니다. 주로 개발과 디버깅 용도이며 예고 없이 변경될 수 있습니다.
<ConfigTable client:load options={appServerOptions} />codex app-server --listen stdio://은 기본 JSONL-over-stdio 동작을 유지합니다. --listen ws://IP:PORT는 WebSocket 전송을 활성화합니다(실험적). 클라이언트 바인딩용 스키마를 생성하는 경우, 게이트된 필드와 메서드를 포함하려면 --experimental을 추가하세요.
codex app
섹션 제목: “codex app”macOS 터미널에서 Codex Desktop을 실행하고 선택적으로 특정 워크스페이스 경로를 엽니다.
<ConfigTable client:load options={appOptions} />codex app은 macOS에서 데스크톱 앱을 설치/열고 제공된 워크스페이스 경로를 엽니다. 이 하위 명령은 macOS 전용입니다.
codex debug app-server send-message-v2
섹션 제목: “codex debug app-server send-message-v2”내장 app-server 테스트 클라이언트를 사용해 app-server의 V2 스레드/턴 흐름으로 메시지 하나를 전송합니다.
<ConfigTable client:load options={debugAppServerSendMessageV2Options} />이 디버그 흐름은 experimentalApi: true로 초기화되며, 스레드를 시작하고 턴을 전송한 후 서버 알림을 스트리밍합니다. 로컬에서 app-server 프로토콜 동작을 재현하고 검사하는 데 사용하세요.
codex apply
섹션 제목: “codex apply”Codex Cloud 작업에서 가장 최근 diff를 로컬 저장소에 적용합니다. 인증되어 있어야 하며 작업에 대한 접근 권한이 필요합니다.
<ConfigTable client:load options={applyOptions} />Codex는 패치된 파일을 출력하며, 예를 들어 충돌로 인해 git apply가 실패하면 비영(0이 아닌) 상태로 종료합니다.
codex cloud
섹션 제목: “codex cloud”터미널에서 Codex cloud 작업과 상호작용합니다. 기본 명령은 대화형 선택기를 열며, codex cloud exec은 작업을 직접 제출하고, codex cloud list는 스크립팅 또는 빠른 확인을 위한 최근 작업을 반환합니다.
<ConfigTable client:load options={cloudExecOptions} />인증은 메인 CLI와 동일한 자격 증명을 따릅니다. 작업 제출이 실패하면 Codex는 비영으로 종료합니다.
codex cloud list
섹션 제목: “codex cloud list”선택적 필터링 및 페이지네이션과 함께 최근 클라우드 작업을 나열합니다.
<ConfigTable client:load options={cloudListOptions} />일반 텍스트 출력은 작업 URL과 상태 세부 정보를 순차적으로 인쇄합니다. 자동화를 위해 --json을 사용하세요. JSON 페이로드에는 tasks 배열과 선택적 cursor 값이 포함됩니다. 각 작업은 id, url, title, status, updated_at, environment_id, environment_label, summary, is_review, attempt_total을 포함합니다.
codex completion
섹션 제목: “codex completion”쉘 완료 스크립트를 생성하고 적절한 위치로 리디렉션합니다. 예: codex completion zsh > "${fpath[1]}/_codex".
<ConfigTable client:load options={completionOptions} />codex features
섹션 제목: “codex features”~/.codex/config.toml에 저장된 기능 플래그를 관리합니다. enable과 disable 명령은 변경 사항을 영구적으로 적용하므로 향후 세션에도 반영됩니다. --profile로 시작하면 루트 구성 대신 해당 프로파일에 기록합니다.
<ConfigTable client:load options={featuresOptions} />codex exec
섹션 제목: “codex exec”codex exec(또는 줄임말 codex e)을 사용해 인간 상호작용 없이 완료되어야 하는 스크립트 또는 CI 스타일 실행을 수행합니다.
<ConfigTable client:load options={execOptions} />Codex는 기본적으로 포맷된 출력을 작성합니다. 상태 변경마다 하나씩 줄바꿈으로 구분된 JSON 이벤트를 받으려면 --json을 추가하세요. 선택적 resume 하위 명령을 사용하면 비대화형 작업을 계속할 수 있습니다. 현재 작업 디렉터리에서 가장 최근 세션을 선택하려면 --last를 사용하고, 모든 세션을 검색하려면 --all을 추가하세요:
<ConfigTable client:load options={execResumeOptions} />codex execpolicy
섹션 제목: “codex execpolicy”execpolicy 규칙 파일을 저장하기 전에 확인하세요. codex execpolicy check는 하나 이상의 --rules 플래그(예: ~/.codex/rules 하위 파일)를 받아들여 가장 엄격한 결정과 일치하는 규칙을 JSON으로 출력합니다. 출력 형식을 보기 좋게 하려면 --pretty를 추가하세요. execpolicy 명령은 현재 프리뷰 상태입니다.
<ConfigTable client:load options={execpolicyOptions} />codex login
섹션 제목: “codex login”CLI를 ChatGPT 계정 또는 API 키로 인증합니다. 플래그 없이 실행하면 Codex가 ChatGPT OAuth 플로우를 위한 브라우저 창을 엽니다.
<ConfigTable client:load options={loginOptions} />자격 증명이 있으면 codex login status가 0으로 종료되므로 자동화 스크립트에서 유용합니다.
codex logout
섹션 제목: “codex logout”저장된 API 키 및 ChatGPT 인증 자격 증명을 모두 제거합니다. 이 명령은 플래그가 없습니다.
codex mcp
섹션 제목: “codex mcp”~/.codex/config.toml에 저장된 Model Context Protocol 서버 항목을 관리합니다.
<ConfigTable client:load options={mcpCommands} />add 서브커맨드는 stdio 및 스트리밍 가능한 HTTP 전송 모두를 지원합니다:
<ConfigTable client:load options={mcpAddOptions} />OAuth 작업(login, logout)은 스트리밍 가능한 HTTP 서버에서만 작동하며(서버에서 OAuth를 지원할 때만) 해당됩니다.
codex mcp-server
섹션 제목: “codex mcp-server”Codex를 stdio를 통해 MCP 서버로 실행하여 다른 도구가 연결할 수 있도록 합니다. 이 명령은 전역 구성 오버라이드를 상속하며 다운스트림 클라이언트가 연결을 닫으면 종료됩니다.
codex resume
섹션 제목: “codex resume”ID로 인터랙티브 세션을 이어가거나 가장 최근 대화를 재개합니다. codex resume은 --last를 기본적으로 현재 작업 디렉터리에 한정하며 --all을 전달하면 전체에서 검색합니다. 모델 및 샌드박스 오버라이드를 포함한 codex와 동일한 전역 플래그를 사용합니다.
<ConfigTable client:load options={resumeOptions} />codex fork
섹션 제목: “codex fork”이전 인터랙티브 세션을 새로운 스레드로 포크합니다. 기본적으로 codex fork는 세션 선택기를 열며, 가장 최근 세션을 포크하려면 --last를 추가하세요.
<ConfigTable client:load options={forkOptions} />codex sandbox
섹션 제목: “codex sandbox”Codex가 내부적으로 사용하는 것과 동일한 정책 하에서 명령을 실행하려면 샌드박스 도우미를 사용하세요.
macOS seatbelt
섹션 제목: “macOS seatbelt”<ConfigTable client:load options={sandboxMacOptions} />Linux Landlock
섹션 제목: “Linux Landlock”<ConfigTable client:load options={sandboxLinuxOptions} />플래그 조합 및 안전 팁
섹션 제목: “플래그 조합 및 안전 팁”- 무인 로컬 작업에는
--full-auto를 설정하되, 전용 샌드박스 VM이 아닌 이상--dangerously-bypass-approvals-and-sandbox와 함께 사용하지 마세요. - Codex에 더 많은 디렉터리에 쓰기 권한을 부여해야 하면
--sandbox danger-full-access를 강제로 사용하는 대신--add-dir을 사용하는 것이 좋습니다. - 머신 리더블 진행 상황과 최종 자연어 요약 둘 다 캡처하려면 CI에서
--json과--output-last-message를 함께 사용하세요.
관련 자료
섹션 제목: “관련 자료”- Codex CLI 개요: 설치, 업그레이드 및 빠른 팁.
- 설정 기본: 모델 및 공급업체와 같은 기본값을 저장합니다.
- 고급 설정: 프로필, 공급업체, 샌드박스 조정 및 통합.
- AGENTS.md: Codex 에이전트 기능과 모범 사례에 대한 개념적 개요.