Codex goal 사용법, 목표만 설정하고 Agent 장기적으로 작동시킨다.

어떤 개발자가 OpenAI Codex에 디바이스 드라이버 프로젝트를 던져놓고 14시간 동안 멈춤 없이 돌렸다는 후기가 돌았다. 사람이 중간에 키를 잡지 않고 그냥 둬도 알아서 계속 굴러갔다는 것이다. 처음 들으면 "이게 가능한가?" 싶지만, 이 마법의 정체가 바로 2026년 4월 말에 Codex CLI에 들어간 /goal 기능이다. 이 글은 그 Codex goal 사용법을 개념부터 끝까지 다룬다.

 

그런데 여기에 함정이 하나 있다. Codex goal 사용법을 개념 없이 명령어만 외워서 쓰면 그냥 비싼 자동완성기가 된다. 토큰만 태우고 엉뚱한 결과가 나온다. 이 기능이 왜 강력한지는 "닫힘 루프(closed-loop)"라는 개념 하나에 다 들어 있는데, 대부분의 글이 이것을 대충 넘긴다.

 

그래서 이 글은 IT를 잘 모르는 사람도 따라올 수 있도록 닫힘 루프와 열림 루프가 무엇인지 비유부터 잡고, 그다음에 /goal 명령어와 강한 목표 작성법, 그리고 언제 쓰면 안 되는지까지 순서대로 짚어본다. 코덱스 goal을 제대로 굴리고 싶다면 끝까지 읽어보면 된다.

 

 

출처: elprocus.com

 

닫힘 루프(closed-loop), 열림 루프(open-loop)란 무엇인가 — 개념부터 잡고 가자

 

이 두 단어는 원래 제어 이론에서 온 용어다. 어렵게 들리지만 자동차 운전으로 비유하면 5초 만에 이해된다.

 

열림 루프(open-loop) — 매번 내가 직접 키를 잡는 방식

 

열림 루프는 기존의 프롬프트 방식이다. 내가 시킨다 → Codex가 한 번 실행한다 → 결과를 내놓고 멈춘다 → 내 다음 지시를 기다린다. 이것으로 끝이다.

 

문제는 매 턴마다 목표를 다시 말해줘야 한다는 점이다. Codex는 전체 목표에 대한 지속적인 맥락이 없다. "이것을 고쳐달라" → 결과가 나온다 → "아직 안 됐으니 계속하라" → 또 결과가 나온다 → "조금 더" 이것을 무한히 반복하게 된다. 한마디로 내가 계속 핸들을 돌리며 운전하는 차다. 손을 떼면 차가 멈춘다.

 

닫힘 루프(closed-loop) — 목적지만 찍어두는 방식

 

닫힘 루프는 /goal이 만드는 방식이다. 작업한다 → 근거를 확인한다 → 더 갈지 끝낼지 스스로 판단한다 → 반복한다. 핵심은 목표가 대화 스레드에 계속 박혀 있다는 것이다.

 

Codex가 미리 정의된 성공 기준에 비추어 진척도를 스스로 평가한다. 스레드가 idle(쉬는) 상태가 되면, 목표를 아직 달성하지 못한 한 알아서 다음 작업을 이어간다. 제어 이론에서 출력을 다시 입력으로 되먹임(feedback)하는 그 닫힘 루프 구조를 그대로 가져온 것이다. 그래서 닫힘 루프다.

 

자율주행으로 한 번에 이해하기

 

요약하면 이렇게 된다.

 

• 열림 루프 = 사람이 매번 핸들을 돌리는 일반 자동차. 손을 떼면 멈춘다.
• 닫힘 루프 = 목적지를 찍어두면 알아서 가는 자율주행차. 손을 떼도 굴러간다.

 

다만 자율주행도 길을 잘못 들면 사람이 끼어들어야 하듯이, 닫힘 루프도 Codex가 엉뚱하게 가면 사람이 개입해야 한다. 이 개입 방법은 뒤에서 다룬다. 일단 "열림 루프는 내가 운전, 닫힘 루프는 목적지만 찍기"만 기억하면 된다.

 

Codex goal이란 정확히 무엇인가 — Ralph 루프의 정체

 

/goal이 닫힘 루프를 만든다는 점은 확인했다. 그렇다면 그 루프 안에서 Codex가 구체적으로 무엇을 반복하는지 봐야 한다. 개발자 커뮤니티에서는 이렇게 에이전트를 목표 달성까지 반복시키는 패턴을 Ralph 루프(Ralph loop)라고 부른다. Codex의 /goal이 바로 이 Ralph 루프를 내장한 것이다.

 

plan → act → test → review → iterate 사이클

 

Ralph 루프는 다섯 단계를 목표가 검증될 때까지 돌리는 패턴이다.

 

1. plan(계획) — 목표를 달성하려면 다음에 무엇을 할지 정한다
2. act(실행) — 코드 수정, 파일 생성 등 실제 작업을 한다
3. test(테스트) — 테스트를 돌리거나 빌드해서 결과를 확인한다
4. review(검토) — 그 결과가 성공 기준에 부합하는지 평가한다
5. iterate(반복) — 아직 멀었으면 다시 plan으로 돌아간다

 

이 사이클이 목표가 충족됐다는 근거가 나올 때까지 자동으로 돈다는 것이 핵심이다.

 

"그냥 재시도"와 무엇이 다른가?

 

여기서 사람들이 헷갈린다. "실패하면 다시 하는 것이라면 그냥 재시도 아닌가?" 아니다. 다르다.

 

단순 재시도는 같은 것을 또 하는 것이다. 그러나 Ralph 루프는 매 사이클마다 평가(review)와 계획(plan)이 들어간다. 결과를 보고 "무엇이 부족한지" 판단한 다음, "그렇다면 다음엔 무엇을 다르게 할지" 새로 정한다. 테스트로 검증까지 한다. 그래서 단순 무한 재시도가 아니라 피드백이 들어간 닫힌 루프인 것이다. 이 차이가 Codex goal 사용법에서 가장 중요한 감각이다.

 

Codex goal 사용법 - 셋업하고 명령어 익히기

 

개념을 잡았으니 이제 실제로 굴려보자. 코덱스 goal 사용법은 설치 → 활성화 → 명령어 순이다.

 

0.128.0 버전부터 가능하다 — 설치와 활성화

 

먼저 버전 확인이 필수다. /goal은 Codex 0.128.0 이상에서만 굴러간다.

 

# 최신 버전으로 설치 또는 업데이트
npm install -g @openai/codex@latest

# 버전 확인
codex --version

 

codex --version을 찍었을 때 0.128.0보다 낮으면 위 설치 명령어를 다시 돌리면 된다.

 

/goal은 아직 실험적 기능이라 기본은 꺼져 있다. 켜는 방법은 두 가지다. CLI 안에서 /experimental 명령어로 켜거나, config.toml의 [features] 섹션에 goals = true를 추가하면 된다.

 

/goal, pause, resume, clear 명령어

 

명령어 자체는 단순하다. 표로 봐두면 된다.

 

명령어	하는 일
`/goal [목표 문장]`	목표를 설정하고 닫힘 루프 시작
`/goal`	현재 설정된 목표 확인
`/goal pause`	자동 진행 일시정지
`/goal resume`	멈춰둔 목표 다시 진행
`/goal clear`	목표 제거, 열림 루프로 복귀

 

여기서 pause와 resume을 실전에서 가장 자주 쓴다. Codex가 엉뚱한 파일을 건드리는 것이 보이면 /goal pause로 멈추고, 범위를 좁혀준 다음 /goal resume으로 다시 보내는 식이다.

 

목표 상태 4가지: Active / Paused / Complete / Budget-limited

 

목표는 살아 있는 동안 4가지 상태(lifecycle) 중 하나에 있다.

 

상태	의미
**Active**	idle 상태가 되면 자동으로 계속 진행한다
**Paused**	진행이 멈춰 있고, 사용자 액션을 기다린다
**Complete**	근거로 목표 달성이 확인됐고 작업이 종료됐다
**Budget-limited**	토큰 예산이 소진돼 진척 요약과 다음 단계를 보고한다

 

자동 진행은 아무 때나 되는 것이 아니다. 목표가 Active이고 + 스레드가 idle이고 + 대기 중인 입력이 없고 + 다른 작업이 없고 + 예산이 남아 있어야 한다. 이 다섯 개가 전부 충족돼야 루프가 굴러간다. 하나라도 빠지면 Codex는 그냥 멈춰서 기다린다.

 

약한 목표 vs 강한 목표 — 여기서 성패가 갈린다

 

Codex goal 사용법에서 명령어보다 100배 중요한 것이 이것이다. 목표 문장을 어떻게 쓰느냐에 따라 결과가 천지 차이로 갈린다. 닫힘 루프는 성공 기준에 비추어 도는 것인데, 그 기준이 흐리멍덩하면 루프가 영원히 끝나지 않거나 엉뚱한 데서 멈춘다.

 

강한 목표를 만드는 6요소

 

OpenAI 공식 쿡북(using_goals_in_codex)은 강한 목표가 갖춰야 할 6요소를 제시한다.

 

1. Outcome(결과) — 작업이 끝났을 때 무엇이 참이어야 하는가
2. Verification surface(검증 근거) — 성공을 증명할 증거. 테스트, 벤치마크, 산출물, 로그 같은 것
3. Constraints(제약) — 작업 도중에 망가지면 안 되는 것
4. Boundaries(경계) — 건드려도 되는 파일·도구·저장소 범위
5. Iteration policy(반복 정책) — 시도와 시도 사이에 다음 행동을 어떻게 고를지
6. Blocked stop condition(중단 조건) — 막혔을 때 언제 멈추고 무엇을 보고할지

 

이것을 한 문장 패턴으로 만들면 이렇게 된다.

 

"<원하는 최종 상태>를 <구체적 증거>로 검증한다. <제약>은 유지하면서 한다. <허용된 입력>만 쓴다. 반복 사이에는 <판단 로직>으로 고른다. 막히면 <중단 조건>에서 멈추고 보고한다."

 

특히 2번 검증 근거(verification surface)가 빠지면 닫힘 루프가 작동하지 못한다. Codex가 "다 됐다"를 스스로 판단할 잣대가 없으니 무한히 돌거나 대충 멈춘다.

 

실전 예시 비교표

 

말로만 하면 와닿지 않으니 약한 목표와 강한 목표를 나란히 봐야 한다.

 

약한 목표 (이렇게 쓰면 망한다)	강한 목표 (이렇게 써야 한다)
`/goal 성능 개선해줘`	`/goal 체크아웃 p95 지연을 120ms 아래로 낮춘다. 체크아웃 벤치마크로 검증하고, 정확성 테스트는 계속 green을 유지한다`
`/goal 이 기능 문서 써줘`	`/goal 라이프사이클·명령어·예시 2개를 담은 문서 페이지를 생성한다. 로컬 빌드 통과 + 명령어가 현재 CLI 동작과 일치하는지로 검증한다`

 

차이가 보이는가? 약한 목표는 "개선"이 어디까지인지, "문서"가 무엇을 담아야 하는지 끝점이 없다. 강한 목표는 "120ms 아래", "벤치마크로 검증", "예시 2개", "로컬 빌드 통과"처럼 측정 가능한 끝점이 박혀 있다. 닫힘 루프는 이 끝점을 보고 멈출 타이밍을 잡는다. 그래서 목표 문장을 쓰는 데 5분을 더 투자하는 것이 토큰 수십 달러를 아끼는 길이다.

 

용도별 사용법은 이렇다. 그냥 막 돌리지 말고...

 

/goal은 만능이 아니다. 잘 맞는 작업과 안 맞는 작업이 명확히 갈린다. 이것을 모르고 아무 데나 쓰면 토큰만 날린다.

 

goal을 쓰면 효과적인 작업

 

핵심 조건은 "경로는 불확실한데 끝점은 명확한 작업"이다. 어디로 가야 할지는 모르겠지만, 도착했는지 아닌지는 확실히 알 수 있는 경우다.

 

• 성능 튜닝 — 목표 수치는 명확하다. 거기까지 가는 길은 여러 갈래다
• flaky 테스트 디버깅 — 가끔 깨지는 테스트. 원인을 찾는 경로가 불확실하다
• 버그 헌팅 — 버그가 어디 있는지 모른다. 그러나 잡았는지는 테스트로 확인 가능하다
• 멀티스텝 리팩터 — 단계가 많고 중간에 시행착오가 필요하다
• 의존성 마이그레이션 — Pydantic v1에서 v2로 올리는 작업 같은 것. 끝점은 "테스트 전부 통과"로 명확하다

 

공통점은 사람이 평소에 "계속 해봐", "조금 더"를 반복하게 되는 작업이라는 것이다. 그 반복을 닫힘 루프가 대신 돌려준다.

 

goal을 쓰면 안 되는 작업 + 실험적 기능 주의점

 

반대로 이런 작업에는 쓰면 안 된다.

 

• 한 줄 수정이나 간단한 질문 — 닫힘 루프 세팅 비용이 작업보다 크다
• 끝점이 모호한 작업 — "더 좋게 만들어달라" 같은 것. 검증할 근거가 없으면 루프가 영원히 끝나지 않는다
• 신뢰할 만한 완료 조건이 없는 작업 — 2번 요소(검증 근거)를 만들 수 없는 작업
• 즉각적인 사용자 제어가 필요한 작업 — 한 스텝마다 사람이 봐야 하는 작업

 

그리고 주의점 몇 가지를 더 챙겨야 한다. /goal은 아직 experimental(실험적) 기능이다. 그래서 다음을 조심해야 한다.

 

• 토큰 예산을 잡지 않으면 비용이 폭주할 수 있다. 닫힘 루프는 알아서 계속 도니까 예산은 명시적으로 정해줘야 한다
• 턴 중간에 compaction(대화 압축)이 발생하면 active goal의 연속성과 audit 요건이 유실되는 문제가 보고됐다 (openai/codex 이슈 #19910)
• 슬래시 명령어의 공식 문서화가 아직 미흡하다

 

그래서 처음에는 작은 목표 + 명확한 예산으로 감을 잡고 점점 키우는 것이 안전하다.

 

사용자 역할이 바뀐다: 운전자에서 항법사로

 

여기가 이 글에서 가장 챙겨갈 부분이다. /goal을 쓰면 사람의 역할 자체가 달라진다.

 

기존 열림 루프에서는 사람이 계속 다음 지시를 던지는 운전자였다. 닫힘 루프에서는 그 역할이 "방향이 맞는지 중간에 검토하는 항법사"로 바뀐다. Codex가 알아서 굴러가니까, 사람은 "지금 올바른 방향으로 가고 있는가"를 확인하는 일을 한다.

 

Codex가 엉뚱한 파일까지 손대기 시작하면 /goal pause로 멈추고, 작업 범위를 좁혀준 뒤 /goal resume으로 다시 보내면 된다. 14시간 동안 멈춤 없이 돌았다는 사례도, 그사이 사람이 아예 손을 놓았다는 것이 아니라 방향만 맞으면 끼어들지 않았다는 의미로 보면 된다. 운전석이 아니라 조수석에서 지도를 보는 사람이 된 것이다.

 

goal은 만능이 아니다, 그러나 알아두면 무기다

 

Codex goal 사용법을 제대로 익히려면 명령어를 외우기 전에 닫힘 루프 개념부터 잡아야 한다는 것이 이 글의 뼈대였다. 챙겨갈 것만 추리면 이렇게 된다.

 

• 열림 루프 vs 닫힘 루프 — 열림은 내가 매번 운전, 닫힘은 목적지를 찍어두면 알아서 간다. /goal은 닫힘 루프를 만든다
• Ralph 루프 — plan → act → test → review → iterate를 목표가 검증될 때까지 반복한다. 단순 재시도와 달리 평가와 계획이 들어간다
• 버전과 명령어 — Codex 0.128.0 이상에서 goals = true로 켜고, /goal, pause, resume, clear로 다룬다
• 강한 목표가 성패를 가른다 — 측정 가능한 결과와 검증 근거를 박은 목표를 써야 한다. "성능 개선해줘"는 망하는 길이다
• 쓸 곳과 쓰지 말 곳 — 경로가 불확실하고 끝점이 명확한 작업에는 효과적이고, 끝점이 모호하거나 한 줄 수정에는 비추천이다

 

/goal은 모든 코딩을 자동화하는 마법봉이 아니다. 실험적 기능이고 토큰도 먹는다. 그러나 성능 튜닝이나 flaky 테스트 디버깅처럼 "계속 해봐"를 반복하던 작업에서는 확실한 무기가 된다. 처음부터 14시간짜리 작업을 던지지 말고, 일단 검증 근거가 명확한 작은 목표 하나로 /goal을 한 번 돌려보면 감이 온다. 거기서부터 코덱스 goal을 키워나가면 된다.