Codex /goal 사용법: 먼저 버전과 완료 기준을 확인하기

Codex /goal은 0.128.0 계열에서 실제로 확인되는 기능이지만, 지금 쓰는 CLI와 화면에서 바로 사용할 수 있는지는 별도로 확인해야 합니다. 2026년 5월 4일 기준 OpenAI의 공개 CLI slash command 문서에는 아직 /goal이 없습니다. 더 강한 근거는 0.128.0 release/source tree와 experimental app-server goal API입니다. 목표가 산출물, 파일 범위, 테스트, 예산, 중단 규칙으로 쪼개질 때만 /goal을 쓰고, 명령이 보이지 않거나 목표가 아직 감사 가능하지 않다면 먼저 /plan으로 정리합니다.

빠른 결론: /goal은 실제 기능이지만 현재 환경 확인이 먼저다

/goal은 단순히 “계속 진행해”를 길게 쓰는 prompt가 아닙니다. Codex 스레드에 장기 목표를 고정해 continuation, pause, resume, budget limit, completion check 동안 같은 목표를 유지하게 하는 workflow입니다. OpenAI Codex 0.128.0 release는 persisted /goal workflows, app-server APIs, model tools, runtime continuation, TUI controls를 언급합니다.

주의할 점은 공개 문서와 로컬 실행 환경이 항상 동시에 움직이지 않는다는 점입니다. 2026년 5월 4일에 확인한 OpenAI Developers CLI slash-command page는 /plan, /status, /resume, /compact, /ps, /stop 등을 보여주지만 /goal은 보이지 않았습니다. IDE slash-command page도 /goal을 IDE 명령으로 설명하지 않습니다. 따라서 기능 존재 여부, 공개 문서, 로컬 CLI, Codex 앱 화면을 분리해서 판단해야 합니다.

먼저 아래 표로 현재 상황을 나눕니다.

이번 검증 환경의 codex --version은 codex-cli 0.125.0이었습니다. 그래서 로컬 환경만으로 /goal 사용 가능성을 증명할 수 없습니다. 기능이 새 버전에 들어왔어도 사용자의 터미널은 아직 오래된 상태일 수 있습니다.

0.128.0 근거로 보는 /goal의 역할

현재 사용자에게 안내할 수 있는 최소 형태는 다음입니다.

text
/goal <objective>

0.128.0의 slash command source는 Goal을 "set or view the goal for a long-running task"라고 설명합니다. inline args를 받을 수 있고, 작업 중에도 사용할 수 있음을 보여줍니다. 또 다른 TUI action source에서는 현재 goal이 없고 objective text도 없을 때 Usage: /goal <objective>가 반환됩니다.

이 때문에 확인되지 않은 subcommand를 만들어 쓰면 안 됩니다. /goal set, /goal audit, /goal complete 같은 형태는 설치된 버전이 명시적으로 보여주지 않는 한 운영 절차에 넣지 않습니다. 0.128.0에서 확인되는 것은 /goal <objective>라는 최소 명령과 그 뒤의 managed lifecycle입니다.

동작 방식은 긴 prompt보다 저장되는 작업 계약에 가깝습니다.

• 스레드에 현재 goal이 저장됩니다.
• runtime continuation이 같은 목표로 진행을 이어갑니다.
• token 및 wall-clock accounting이 예산 판단에 참여합니다.
• budget limit에 도달하면 새 작업을 시작하지 않고 wrap up해야 합니다.
• app-server에는 thread/goal/set, thread/goal/get, thread/goal/clear가 있습니다.
• TUI에는 create, pause, resume, clear에 해당하는 제어가 있습니다.

안전 설계도 중요합니다. continuation template은 objective를 untrusted user data로 다루고, 완료를 선언하기 전에 실제 deliverables와 증거를 확인하도록 요구합니다. budget-limit template은 예산에 도달하면 작업을 넓히지 말고 정리하게 합니다. 즉 /goal은 “스스로 끝낼 때까지 무한 실행”이 아니라 persistence, continuation, audit, budget stop을 묶은 기능입니다.

/goal이 보이지 않을 때 확인할 것

명령이 없을 때는 먼저 버전을 확인합니다.

bash
codex --version

codex-cli 0.128.0보다 낮다면 문법 문제가 아닐 수 있습니다. 업데이트하고 터미널 또는 Codex 세션을 다시 연 뒤 slash menu를 다시 봅니다.

다음은 화면 구분입니다. CLI, IDE, desktop app, app-server integration은 같은 표면이 아닙니다. 공개 문서는 참고 자료이지만, 실제로 입력 가능한 명령은 현재 실행 중인 binary와 UI가 결정합니다.

마지막으로 app-server를 일반 CLI 명령과 섞지 않습니다. app-server API overview는 thread/goal/set, thread/goal/get, thread/goal/clear를 보여주며, capabilities.experimentalApi 뒤에 둡니다. goal이 thread concept으로 존재한다는 증거이지만, 일반 사용자가 experimental API를 직접 의존해도 된다는 뜻은 아닙니다.

실무 순서는 다음이 안전합니다.

1. codex --version을 실행합니다.
2. CLI 세션에서 slash command 목록을 확인합니다.
3. 현재 위치가 CLI, IDE, 앱, app-server integration 중 어디인지 봅니다.
4. /goal이 없다면 /plan으로 목표를 먼저 감사 가능하게 만듭니다.
5. 업데이트 후 또는 CLI로 돌아간 후 command surface를 다시 확인합니다.

안전한 결론은 “현재 화면에서는 확인되지 않았다”입니다. 기능 자체가 없다고 단정할 필요는 없습니다.

/goal에 넣을 목표를 쓰는 법

/goal은 objective가 감사 가능할 때만 효과가 있습니다. 모호한 목표를 넣으면 에이전트는 오래 움직일 수 있지만, 완료 판단은 어려워집니다. 좋은 목표에는 결과, 파일 범위, 검증 방법, 보고할 증거, 중단 조건이 포함됩니다.

권장 형태는 다음입니다.

text
/goal <파일 또는 모듈>에서 <구체적 결과>를 구현한다.
Acceptance criteria:
- User-visible behavior: <무엇이 바뀌어야 하는가>
- Files in scope: <편집 가능한 경로>
- Verification: <테스트, 명령, 스크린샷, 로그, 수동 확인>
- Evidence to report: <diff summary, test output, risks, remaining work>
- Stop rule: <budget, credential 부족, dependency 실패, 불명확한 결정>

약한 목표는 다음과 같습니다.

text
/goal dashboard 개선

실행 가능한 목표는 이렇게 바뀝니다.

text
/goal billing usage table에 CSV export를 추가한다.
Acceptance criteria:
- export action은 기존 filter 옆에 둔다.
- 편집 범위는 app/billing과 shared CSV utilities로 제한한다.
- CSV에는 account id, period, model, tokens, cost, status를 포함한다.
- npm test -- billing 및 npm run lint를 실행한다.
- billing API가 raw row data를 제공하지 않으면 중단하고 부족한 정보를 보고한다.

두 번째 형태는 Codex가 진행할 수 있는 범위와 멈춰야 할 지점을 동시에 줍니다. 이 정도로 못 쓰겠다면 /plan이 먼저입니다. 로그인 경로, API key, 구독, billing route가 문제라면 Codex API 키와 ChatGPT 구독 차이를 확인하고, 긴 작업의 예산과 한도는 OpenAI Codex 사용량 제한 가이드와 함께 봅니다. 로컬 설정 문제는 Codex config.toml이 더 맞습니다.

긴 작업에서의 안전한 흐름

기본 흐름은 plan, set, monitor, verify, clear or continue입니다. UI 이름은 달라도 감사 모델은 같아야 합니다.

가장 위험한 실패는 긴 transcript를 완료 증거로 착각하는 것입니다. 결과를 받아들이기 전에 아래를 확인합니다.

• 변경된 파일이 선언한 scope 안에 있는가?
• 약속한 테스트를 실행했거나, 실행하지 못한 이유가 있는가?
• 요약 말고 실제 artifact가 있는가?
• 관련 없는 refactor나 숨은 product decision이 없는가?
• budget-limited 상태에서 새 작업을 시작하지 않고 wrap up했는가?
• 계속할 이유가 분명한가, 아니면 goal을 clear해야 하는가?

답이 약하면 완료가 아닙니다. 증거를 요구하거나 objective를 고치거나 멈춥니다. /goal은 continuity를 높이는 도구이지 review 기준을 낮추는 도구가 아닙니다.

/goal을 쓰지 않는 편이 나은 경우

문제가 아직 모호하면 /goal로 시작하지 않습니다. 넓은 brainstorming, 낯선 codebase 탐색, success condition이 없는 조사, production 권한이 필요한데 허가되지 않은 작업, 예산을 모르는 장시간 실행에는 맞지 않습니다.

피해야 할 상황은 다음과 같습니다.

• credential, production access, policy decision이 필요하지만 경계가 확인되지 않았다.
• 변경 범위가 너무 넓어 review가 불가능하다.
• stop rule을 말할 수 없다.
• 완료를 어떻게 판단할지 알 수 없다.
• 약한 prompt를 긴 실행 시간으로 보완하려 한다.

작은 작업은 일반 prompt로 충분합니다. 분해가 필요하면 /plan, 대화 연속성이 필요하면 /resume 또는 /compact가 더 맞습니다. /goal은 persistence가 필요할 정도로 크고, audit가 가능할 정도로 구체적인 일에 적합합니다.

다른 coding agent와의 운영 방식은 Claude Code vs Codex에서 비교할 수 있습니다. 중요한 것은 자율성의 느낌이 아니라, 최종 상태가 기준과 맞는지 증명하는 능력입니다.

자주 묻는 질문

Codex /goal은 지금 사용할 수 있나요?

2026년 5월 4일 확인한 0.128.0 release/source evidence에는 존재합니다. 다만 공개 CLI/IDE command 문서는 뒤처져 있었으므로 로컬 version과 command surface를 확인해야 합니다.

구문은 무엇인가요?

신뢰할 수 있는 최소 형태는 /goal <objective>입니다. 추가 subcommand는 설치된 버전이 명시하지 않는 한 가정하지 않습니다.

내 CLI에 /goal이 없는 이유는 무엇인가요?

오래된 CLI, 다른 화면, 문서와 구현의 지연이 흔한 이유입니다. codex --version과 slash menu를 확인하세요.

/goal은 /plan과 같은가요?

아닙니다. /plan은 목표를 정리하는 단계이고, /goal은 감사 가능한 목표를 지속 실행하는 단계입니다.

밤새 unattended로 실행해도 되나요?

기본 운영 방식으로 보지 않습니다. budget, acceptance criteria, file scope, reviewable evidence가 필요합니다. budget-limited wrap-up은 성공이 아닙니다.

app-server goal API를 써야 하나요?

experimental app-server integration을 의도적으로 만들고 capabilities.experimentalApi를 확인한 경우에만 고려합니다. 일반 사용은 CLI command surface 확인에서 시작합니다.