# Codex /goal 사용법: 활성화부터 목표 수정·완료 확인까지

> Codex 입력창에서 /goal 뒤에 달성할 결과를 적으면 현재 대화에 목표가 저장됩니다. 명령이 보이지 않으면 지원 버전과 features.goals 설정을 확인하세요. 목표를 수정하거나 잠시 멈출 수 있으며, 완료 여부는 변경 파일과 테스트 결과로 판단합니다.

- URL: https://blog.laozhang.ai/ko/posts/codex-goal
- Published: 2026-05-04
- Updated: 2026-10-08
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: 개발 도구·에이전트
- Tags: OpenAI Codex, Codex CLI, Codex /goal, AI 코딩 에이전트, 개발 도구

---
Codex에서 `/goal`을 쓰려면 <strong>Codex 입력창에 `/goal`과 달성할 결과를 함께 입력</strong>합니다. 현재 대화에 목표가 저장되고, Codex는 작업 결과를 확인하면서 다음 단계로 이어갈 수 있습니다. 명령이 목록에 없다면 지원 버전과 `features.goals` 설정부터 확인하세요. 현재 [공식 명령 안내](https://learn.chatgpt.com/docs/developer-commands?surface=cli#set-or-view-a-task-goal-with-goal)에는 목표 설정·조회뿐 아니라 수정, 일시정지, 재개, 삭제도 문서화되어 있습니다.

한 줄을 고치거나 설명 하나를 듣고 끝낼 일에는 일반 요청으로 충분합니다. `/goal`은 재현, 수정, 테스트를 여러 차례 거쳐야 하지만 <strong>어떤 결과가 나오면 끝낼지 분명한 작업</strong>에 적합합니다. 예를 들어 “페이지 나누기를 개선해 줘”보다 “첫 페이지에서 항목이 빠지는 문제를 고치고, 빈 목록과 마지막 페이지 테스트까지 통과시켜 줘”가 완료 여부를 판단하기 쉽습니다.

이 안내는 2026년 10월 7일 확인한 공식 문서를 기준으로 작성했습니다. 아래 작업 예시는 사용법을 설명하기 위해 만든 것이며, 실제 Codex 실행 결과나 장시간 성능 측정은 아닙니다.

## `/goal`은 어디에 입력하나요?

터미널에서 실행한 Codex CLI라면 <strong>Codex의 대화 입력란</strong>에 입력합니다. 셸에 `codex /goal ...`을 입력하는 방식으로 설명된 명령이 아닙니다. 먼저 Codex 세션을 열고 `/` 명령 목록을 확인한 뒤 목표를 넣으세요.

```text
/goal 페이지 나누기 함수에서 첫 항목이 누락되는 문제를 고치고 관련 테스트를 통과시켜 줘.
```

위 문장은 시작 방법만 보여 주는 짧은 예시입니다. 실제로 맡길 때는 수정할 파일, 기대하는 출력, 검증 방법을 함께 적는 편이 좋습니다. 목표가 설정되면 `/goal`로 현재 목표를 조회해 의도한 내용이 저장되었는지 확인합니다. [공식 목표 명령 안내](https://learn.chatgpt.com/docs/developer-commands?surface=cli#set-or-view-a-task-goal-with-goal)

공식 명령 가이드에는 데스크톱 앱과 IDE의 명령 목록에도 `/goal`이 나옵니다. 다만 CLI에서 확인한 버전이나 명령 목록이 다른 클라이언트의 사용 가능 여부까지 증명하지는 않습니다. 앱이나 IDE를 쓰고 있다면 그 입력창의 `/` 목록을 확인하세요. 목록에 없다면 아래 활성화 절차와 해당 클라이언트의 버전을 함께 확인해야 합니다.

## Codex `/goal`이 없을 때: 버전과 기능 설정 확인

<strong>공식 Cookbook은 Goals가 Codex 0.128.0부터 제공된다고 설명합니다.</strong> 이 숫자는 기능이 처음 포함된 버전이며, 현재 최신 버전이라는 뜻은 아닙니다. 먼저 셸에서 CLI 버전을 확인합니다. [Goals 시작 안내](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)

```bash
codex --version
```

CLI가 오래되었다면 설치한 방식에 맞춰 업데이트하세요. npm으로 설치한 경우 공식 안내는 다음과 같습니다.

```bash
npm install -g @openai/codex@latest
codex --version
```

Homebrew로 설치했다면 다음 명령을 사용합니다.

```bash
brew update
brew upgrade --cask codex
codex --version
```

두 설치 방식을 모두 실행할 필요는 없습니다. 업데이트 후 Codex를 다시 열어 `/` 목록에서 `/goal`을 확인하세요. 앱이나 IDE를 사용하는 경우에는 CLI 업데이트만으로 해당 앱이나 확장 프로그램까지 업데이트되었다고 판단하지 않습니다.

지원 버전인데 명령이 없다면, 공식 [Follow a goal](https://learn.chatgpt.com/use-cases/follow-goals#introduction)은 `config.toml`에서 다음 기능을 켜도록 안내합니다.

```toml
[features]
goals = true
```

이미 `[features]` 항목이 있다면 그 안에 `goals = true`를 넣으세요. 같은 테이블을 파일에 다시 추가하지 않습니다. CLI에서 기능을 활성화하는 공식 명령도 있습니다.

```bash
codex features enable goals
```

설정 파일 편집과 CLI 명령은 같은 기능을 켜기 위한 선택지입니다. `multi_agent = true`를 추가하거나 `config.yaml`을 만드는 것이 이 공식 활성화 절차의 전제는 아닙니다. 설정을 확인한 뒤 Codex를 다시 열고 `/goal`이 나타나는지 확인합니다.

![Codex의 버전과 명령 입력 위치를 확인하는 흐름](https://blog.laozhang.ai/posts/ko/codex-goal/img/explainer-1.webp)

명령 목록에 여전히 없다면 <strong>“내가 쓰는 클라이언트에서 명령이 나타나지 않는다”</strong>는 문제로 좁혀 보세요. 사용 중인 앱·CLI·IDE, 각각의 버전, 실제로 적용한 설정을 구분하면 다음 확인 지점이 명확해집니다. 기능 설정만으로 모든 앱 오류가 해결된다고 보장할 수는 없습니다.

## 목표 설정·조회·수정·중단 명령

아래 명령은 Codex 대화 입력창에서 사용합니다. 목표를 만드는 문장은 비어 있으면 안 되며, 공식 안내상 <strong>최대 4,000자</strong>입니다. 설명이 길다면 세부 조건을 프로젝트 파일에 적고 목표에서 그 파일을 가리킬 수 있습니다. [현재 명령과 길이 제한](https://learn.chatgpt.com/docs/developer-commands?surface=cli#set-or-view-a-task-goal-with-goal)

| 명령 | 할 수 있는 일 | 사용할 때 |
| --- | --- | --- |
| `/goal <달성할 결과>` | 현재 대화의 목표 설정 | 작업을 시작할 때 |
| `/goal` | 현재 목표 조회 | 목표와 진행 상태를 확인할 때 |
| `/goal edit` | 목표 내용 수정 | 완료 조건이나 작업 범위를 고칠 때 |
| `/goal pause` | 목표 일시정지 | 변경 내용을 검토하거나 판단을 보류할 때 |
| `/goal resume` | 일시정지한 목표 재개 | 계속할 조건을 확인한 뒤 |
| `/goal clear` | 현재 목표 제거 | 목표를 더 이상 유지할 필요가 없을 때 |

`/goal edit`가 현재 공식 가이드에 있으므로, 예전 안내에 수정 명령이 없다는 이유로 사용할 수 없다고 단정하면 안 됩니다. 편집한 뒤에는 `/goal`로 목표를 다시 조회해 완료 조건이 정확한지 확인하세요.

일시정지나 삭제는 <strong>목표의 진행을 제어하는 동작</strong>입니다. 이미 바뀐 파일이나 실행된 외부 요청을 되돌리는 기능으로 생각하면 안 됩니다. 파일을 원래 상태로 돌려야 한다면 별도로 변경 내역을 확인하고 복구해야 합니다.

또한 위 공식 목록에는 `/goal budget`, `/goal status`, `/goal complete` 같은 명령이 없습니다. 예산 설정과 완료 선언을 위해 임의의 하위 명령을 만들어 입력하지 마세요. 목표 상태 조회에는 `/goal`을 사용합니다.

## 그대로 응용할 수 있는 예시: 페이지에서 항목이 빠지는 버그

다음은 <strong>TypeScript 프로젝트에 페이지 나누기 함수와 Vitest 테스트가 이미 있는 상황</strong>을 가정한 예시입니다. `package.json`의 `test` 스크립트는 `vitest run`으로 한 번 실행 후 종료하고, `typecheck` 스크립트도 있어야 합니다. 실제 저장소의 파일명과 명령이 다르면 그 부분부터 바꿉니다. 이 예시의 명령을 이 글에서 실행한 것은 아닙니다.

함수는 `paginate(items, page, pageSize)`이고, 페이지 번호는 1부터 시작한다고 정합니다. 현재 문제가 첫 페이지에서 첫 항목이 빠지는 것이라면 “테스트를 통과해 줘”만으로는 충분하지 않습니다. 잘못된 기대값을 바꿔 통과시키는 일을 막으려면 올바른 출력도 함께 지정해야 합니다.

| 확인할 입력 | 기대하는 결과 | 확인하는 문제 |
| --- | --- | --- |
| `paginate([1, 2, 3, 4, 5], 1, 2)` | `[1, 2]` | 첫 항목이 빠지지 않는가 |
| 같은 목록의 2페이지, 페이지 크기 2 | `[3, 4]` | 페이지 사이에 누락·중복이 없는가 |
| 같은 목록의 3페이지, 페이지 크기 2 | `[5]` | 마지막 페이지의 남은 항목을 보존하는가 |
| `paginate([], 1, 2)` | `[]` | 빈 목록을 처리하는가 |
| 페이지 번호 0 또는 페이지 크기 0 | `RangeError` | 정한 입력 규칙을 지키는가 |

위 입력 규칙은 예시 프로젝트에서 정한 조건입니다. 기존 서비스가 잘못된 입력에 다른 방식으로 대응한다면, 실제 공개 동작을 확인한 뒤 목표를 작성해야 합니다. 기존 배열을 변경하지 않는 조건도 넣으면 페이지 계산을 고치다가 호출한 쪽의 데이터까지 바꾸는 일을 막을 수 있습니다.

Codex 입력창에는 다음처럼 한 목표로 묶어 넣을 수 있습니다.

```text
/goal src/lib/paginate.ts에서 첫 페이지의 첫 항목이 빠지는 버그를 수정해 줘.
페이지 번호는 1부터 시작하고, 페이지 크기는 양의 정수야.
[1, 2, 3, 4, 5]를 크기 2로 나누면 1·2·3페이지는 각각
[1, 2], [3, 4], [5]여야 해. 빈 목록은 []를 반환하고,
페이지 번호나 크기가 0이면 RangeError를 발생시켜야 해.
입력 배열을 변경하지 말고 함수 이름과 인자 순서를 유지해 줘.
수정 범위는 src/lib/paginate.ts와 src/lib/paginate.test.ts야.
먼저 기존 구현과 테스트를 읽고 버그를 재현한 뒤 수정해 줘.
npm run test -- src/lib/paginate.test.ts와 npm run typecheck로 검증해 줘.
테스트 실행 자체가 막히면 설정이나 의존성을 임의로 바꾸지 말고,
실행한 명령, 막힌 이유, 남은 검증을 보고해 줘.
마지막에는 변경 파일과 각 입력의 검증 결과를 제시해 줘.
커밋이나 원격 반영은 하지 마.
```

이 목표는 다음에 어떤 수정부터 할지까지 강제로 정하지 않습니다. Codex가 구현을 읽고 실패 원인을 찾을 여지를 주면서, 결과·범위·검증은 명확하게 남깁니다. 문장이 길어져도 관련 없는 기능을 같은 목표에 계속 추가하지 않는 편이 좋습니다.

### 완료 보고를 받을 때 무엇을 확인하나요?

이 예시에서는 <strong>관련 테스트 통과, 타입 검사 통과, 허용된 파일만 변경</strong>이라는 세 조건을 함께 봅니다. 테스트가 초록색이어도 함수가 입력 배열을 바꾸거나 공개 인자 순서가 달라졌다면 목표를 달성한 것이 아닙니다.

최종 보고에서 실제 실행 명령과 결과를 확인하고, 변경 내역에서 다섯 입력 조건이 테스트에 반영되어 있는지 봅니다. “모두 검증했습니다”라는 문장만으로는 어떤 테스트가 실행되었는지 알 수 없습니다. 테스트 실행이 막혔다면 코드 수정과 검증 완료를 구분해야 합니다.

예를 들어 첫 페이지와 빈 목록만 통과하고 마지막 페이지가 실패하면 수정은 일부 진행된 상태입니다. 타입 검사를 실행하지 못했다면 “타입 검사 미확인”이 남아 있습니다. 이런 남은 작업을 표시하는 것이 긴 대화나 변경 파일 수를 완료 증거로 삼는 것보다 유용합니다.

![목표를 설정하고 작업 결과를 검증한 뒤 계속할지 결정하는 흐름](https://blog.laozhang.ai/posts/ko/codex-goal/img/explainer-2.webp)

## 목표가 계속되는 조건과 멈추는 조건

`/goal`의 목표는 <strong>현재 대화에 저장되는 상태</strong>입니다. 다른 모든 대화에서 자동으로 적용되는 전역 기억이나 프로젝트 지침과는 다릅니다. 같은 대화에서 여러 단계의 작업을 이어갈 때 목표를 다시 설명할 필요를 줄이는 기능입니다. [공식 Goals 동작 설명](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)

공식 Cookbook에 따르면 자동으로 다음 작업을 검토하는 시점은 대화가 쉬고 있을 때입니다. 목표가 활성 상태이고 예산이 남아 있어야 하며, 다른 응답이 진행 중이거나 사용자 입력·대기 작업이 있으면 동시에 계속하지 않습니다. 계획만 작성한 작업은 자동 계속으로 이어지지 않고, 중단은 목표를 일시정지시킵니다. 자동으로 이어진 응답에서 도구 호출이 없으면 다음 자동 계속을 억제하는 동작도 설명되어 있습니다.

따라서 목표가 활성 상태라는 것만으로 끝없이 실행된다고 볼 수는 없습니다. 목표 달성, 사용자의 일시정지·삭제, 실행 중단, 예산 한도, 추가 입력이 필요한 장애물 등에서 멈출 수 있습니다. 이 문서상의 동작을 컴퓨터가 꺼져도 실행되는 클라우드 예약 작업이나 정해진 시간의 무인 실행 보장으로 확대해서는 안 됩니다.

목표를 오래 유지할수록 중간 보고는 짧고 구체적인 편이 좋습니다. “진행 중” 대신 “첫 항목 누락을 재현했고 첫·둘째 페이지 테스트는 통과했으며 마지막 페이지는 확인 중”이라고 보고하면 현재 남은 일이 보입니다. 같은 실패가 이어지면 실패 로그를 읽고 다음 시도의 이유를 설명하도록 목표를 다듬으세요.

## 토큰 예산을 다 쓰면 완료된 건가요?

<strong>아닙니다. 예산 소진은 작업을 멈추고 진행 상황을 정리해야 하는 경계</strong>이며, 목표 달성의 증거가 아닙니다. 공식 Cookbook은 예산에 도달하면 실질적인 새 작업을 중단하고, 진행 내용·막힌 점·다음 단계를 요약하도록 설명합니다. [Goals의 예산 처리](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)

일반 사용자는 현재 클라이언트가 제공하는 목표·사용량 정보를 확인하고, 재개 전에 남은 검증과 허용한 범위를 판단하면 됩니다. 목표에 “세 번 시도한 뒤 보고해 줘”라고 적을 수는 있지만, 그 문장은 작업 지시이지 엔진에 구현된 강제 호출 한도는 아닙니다. 이를 정확한 비용 차단 장치로 취급하면 안 됩니다.

개발자가 Codex를 자체 도구에 연결하는 경우에는 [app-server의 목표 API](https://learn.chatgpt.com/docs/app-server#manage-a-thread-goal)가 별도로 있습니다. `thread/goal/set`, `thread/goal/get`, `thread/goal/clear`로 목표 상태를 관리하며, 공식 예시는 `tokenBudget`, `tokensUsed`, `timeUsedSeconds`를 보여 줍니다. 일반 입력창에서 `/goal`을 쓰기 위해 이 API를 직접 연결할 필요는 없습니다.

API 문서상 새로운 목표로 교체하면 사용량 집계가 초기화됩니다. 진행이 끝나지 않은 동일한 목표를 지정하거나 목표 문장을 생략해 상태·예산만 바꾸면 사용 이력을 유지합니다. 따라서 기록의 숫자를 비교할 때는 같은 목표의 집계인지도 확인해야 합니다. API의 토큰 예산은 달러 금액이나 ChatGPT 구독의 남은 사용량으로 바로 환산할 수 없습니다.

실제 지출 계획이 필요하다면 [Codex CLI의 하루 API 비용과 긴 작업 예산 계산](https://blog.laozhang.ai/ko/posts/codex-cli-token-cost-estimate)을 별도로 참고하세요. 목표를 멈추는 기준과 어떤 방식으로 청구되는지는 구분해서 판단해야 합니다.

## `Failed to read thread goal` 같은 오류가 나오면

<strong>명령이 목록에 없는 상황과 목표를 읽거나 저장하다가 실패한 상황은 구분</strong>해야 합니다. `Failed to set thread goal`, `Failed to update thread goal`, `Failed to read thread goal`만으로 원인을 하나로 정할 수는 없습니다.

먼저 실패한 동작이 시작·조회·수정 중 무엇이었는지, 사용하는 클라이언트와 버전, 오류의 전체 문구를 기록하세요. 조회가 가능하다면 `/goal`로 현재 목표가 남아 있는지도 확인합니다. 명령이 아예 없는 경우에는 앞서 설명한 지원 버전과 기능 설정을 확인하고, 명령이 있지만 읽기·저장이 실패하는 경우에는 그 실패와 관련된 로그를 기준으로 다음 조치를 판단해야 합니다.

이때 목표를 지우거나 새 목표를 덮어쓰기 전에 기존 목표와 미완료 작업을 보존하는 편이 좋습니다. API 키나 개인 경로 등 민감한 정보는 공유 로그에서 가리고, 오류 문구만 보고 인증 정보를 초기화하거나 대화 저장소를 삭제하지 마세요. 현재 공식 자료만으로 모든 읽기·저장 오류에 공통으로 적용할 해결책은 확인되지 않습니다.

## 자주 묻는 질문

### `/goal`과 일반 요청은 언제 나눠 쓰나요?

한 번의 수정이나 설명이면 일반 요청으로 충분합니다. `/goal`은 다음 행동이 조사·테스트 결과에 따라 달라지고, 여러 단계 뒤에 확인할 명확한 결과가 있을 때 적합합니다. 끝낼 기준이 모호하다면 먼저 원하는 결과와 검증 방법을 정하세요. [공식 사용 기준](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)

### 현재 목표의 문장을 바꿀 수 있나요?

현재 공식 명령 안내에는 `/goal edit`가 있습니다. 완료 조건이나 허용 범위를 수정한 뒤 `/goal`로 내용을 확인하세요. 짧은 명령 목록에 `edit`가 빠져 있다고 해서 현재 기능도 없다고 판단하지 않습니다. [목표 수정 명령](https://learn.chatgpt.com/docs/developer-commands?surface=cli#set-or-view-a-task-goal-with-goal)

### 목표를 삭제하면 코드도 원래대로 돌아가나요?

아닙니다. `/goal clear`는 현재 목표를 제거하는 명령입니다. 파일 변경을 취소하는 동작이 아니므로, 복구가 필요하면 변경 내역을 별도로 검토해야 합니다. [목표 삭제 명령](https://learn.chatgpt.com/docs/developer-commands?surface=cli#set-or-view-a-task-goal-with-goal)

### `/goal`을 켜려면 멀티 에이전트 설정도 필요한가요?

공식 활성화 안내는 `config.toml`의 `[features]` 아래 `goals = true` 또는 `codex features enable goals`입니다. 이 안내는 멀티 에이전트 설정을 전제로 하지 않습니다. 먼저 자신이 쓰는 클라이언트가 Goals를 지원하는지 확인하세요. [공식 활성화 방법](https://learn.chatgpt.com/use-cases/follow-goals#introduction)

### 밤새 켜 두면 알아서 끝나나요?

공식 자료는 여러 단계의 독립적인 작업을 설명하지만, 특정 시간 안에 성공하거나 무제한으로 계속한다고 보장하지 않습니다. 목표가 명확해도 예산이나 장애물 때문에 미완료로 멈출 수 있습니다. 재개 전에 남은 작업을 확인하고, 최종 결과는 실제 파일·테스트·산출물로 판단하세요. [계속·중단·완료 조건](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex)

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-10-08.

- [공식 명령 안내](https://learn.chatgpt.com/docs/developer-commands?surface=cli) (learn.chatgpt.com)
- [Goals 시작 안내](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex) (developers.openai.com)
- [Follow a goal](https://learn.chatgpt.com/use-cases/follow-goals) (learn.chatgpt.com)
- [app-server의 목표 API](https://learn.chatgpt.com/docs/app-server) (learn.chatgpt.com)