Codex 사용량·한도 확인: 5시간·주간 리셋 시각 보는 법

Codex CLI에 “ok” 한 단어만 답하라고 시켜 봤습니다. 돌아온 답은 정말 “ok” 한 단어인데, 들어간 입력은 21,285토큰이었어요. 시스템 지시와 도구 정의가 요청마다 실리기 때문입니다.

로그가 든 예제 폴더에서 로그 파일을 통째로 맡기자 88,393토큰까지 올라갔고요.

ChatGPT 계정으로 쓰는 Codex는 메시지 개수가 아니라 이렇게 처리한 양만큼 한도가 줄어듭니다. 한도는 5시간 창과 주간 창 두 개가 동시에 줄고, 남은 양은 CLI 대화 화면에서 /status를 입력하거나 ChatGPT 웹의 Codex 사용량 화면에서 볼 수 있어요. 스크립트에서 숫자로 받으려면 codex app-server의 account/rateLimits/read로 사용률(%)과 리셋 시각을 읽으면 됩니다.

2026년 9월 29일 Windows 11 · Windows PowerShell 5.1 테스트 환경에서 Codex CLI 0.158.0에 ChatGPT 계정으로 로그인해 직접 실행한 결과이고, 공식 가격·앱 서버·AGENTS.md 문서도 같은 날 확인했습니다.

요금제별 한도 수치는 자주 바뀌어 옮기지 않고 공식 가격 문서로 연결합니다.

설치부터 필요하다면 Codex CLI 설치 방법과 설치 확인을 먼저 보세요.

남은 양을 보는 곳

스크립트로 한도를 읽으면 이렇게 나옵니다.

primary: 56% used, window 300 min, resets 2026. 9. 29. AM 11:40:25
secondary: 54% used, window 10080 min, resets 2026. 10. 4. AM 5:28:37

primary는 창 길이 300분, 즉 5시간 창이고 secondary는 10,080분(7일), 즉 주간 창입니다. 이 계정은 5시간 창을 56% 써서 오전 11시 40분에 초기화되고, 주간 창은 54%를 써서 10월 4일 새벽에 초기화된다는 뜻이에요.

남은 양은 세 군데에서 볼 수 있습니다.

방법	어디서	보이는 것
/status	Codex CLI 대화 화면	현재 남은 한도
사용량 화면	ChatGPT 웹 Codex 설정 > Usage	현재 한도
account/rateLimits/read	스크립트, 외부 도구	창별 사용률·리셋 시각

대화 화면에서 일하는 중이라면 /status가 제일 빠릅니다. 10월 13일 Codex CLI 0.162.1에서 연 화면입니다.

스크립트로 읽을 때와 달리 여기서는 쓴 양이 아니라 남은 양(left)으로 보여 줍니다. 주간 창은 초기화 날짜까지 붙어 나와요.

앱 서버가 필요한 건 작업 전에 남은 양을 확인하고 멈추는 스크립트처럼, 대화 화면 밖에서 숫자로 받아야 할 때예요. codex exec --json은 요청마다 쓴 토큰(usage)은 알려 주지만 사용률이나 리셋 시각은 주지 않았습니다.

5시간 한도가 언제 초기화되는지도 앱 서버 응답의 resetsAt이 알려 줍니다. 오전 9시 47분에 읽었을 때 5시간 창의 초기화 시각은 오전 11시 40분이었어요. 창이 언제부터 세어지는지는 공식 문서에 없어서, 추측하기보다 /status나 resetsAt으로 확인하시길 권합니다.

앱 서버로 한도를 읽는 스크립트

앱 서버는 Codex를 다른 프로그램에 붙일 때 쓰는 JSON-RPC 서버로, codex app-server로 띄워 표준 입출력으로 대화합니다. 연결마다 initialize 요청을 한 번 보내고 initialized 알림으로 응답한 뒤에 다른 메서드를 부를 수 있어요. 아래를 codex-limits.mjs로 저장하고 node codex-limits.mjs로 실행하면 위 출력이 나옵니다.

// Prints the Codex 5-hour and weekly usage windows. Uses only the read method.
import { spawn } from 'node:child_process'

const server = spawn(process.env.ComSpec ?? 'cmd.exe', ['/c', 'codex', 'app-server'], { stdio: ['pipe', 'pipe', 'ignore'] })
const waiting = new Map()
let rest = ''
server.stdout.on('data', (chunk) => {
  const lines = (rest + chunk).split('\n')
  rest = lines.pop()
  for (const line of lines.filter((l) => l.trim())) {
    const msg = JSON.parse(line)
    waiting.get(msg.id)?.(msg)
  }
})
let id = 0
const call = (method, params) => new Promise((resolve) => {
  waiting.set(++id, resolve)
  server.stdin.write(JSON.stringify({ id, method, params }) + '\n')
})

await call('initialize', { clientInfo: { name: 'limits-check', version: '1.0.0' } })
server.stdin.write(JSON.stringify({ method: 'initialized' }) + '\n')
const { result, error } = await call('account/rateLimits/read', null)
if (error) throw new Error(error.message)

const show = (label, w) => w && console.log(
  `${label}: ${w.usedPercent}% used, window ${w.windowDurationMins} min, resets ${new Date(w.resetsAt * 1000).toLocaleString('ko-KR')}`,
)
show('primary', result.rateLimits.primary)
show('secondary', result.rateLimits.secondary)
server.kill()
process.exit(0)

usedPercent는 그 창 안에서 지금까지 쓴 비율, resetsAt은 다음 리셋 시각(초 단위 Unix 시각)입니다. 응답에는 요금제 이름(planType)도 들어 있지만 출력하지 않았어요. Windows용으로 cmd.exe를 거쳐 띄우게 썼으니, macOS·Linux에서는 spawn('codex', ['app-server'], …)로 바꿔야 합니다.

주의: 앱 서버 응답 스키마에는 한도 초기화 크레딧을 쓰는 메서드(account/rateLimitResetCredit/consume)도 있습니다. 읽기용 스크립트에서는 account/rateLimits/read만 부르세요.

앱 서버는 실험적 기능이라 이후 버전에서 형식이 바뀔 수 있습니다.

한도가 줄어드는 방식

공식 가격 문서를 보면 이렇습니다.

• 요금제별로 “5시간당 로컬 메시지 수”의 추정 범위를 보여 줍니다.
• 주간 한도가 5시간 창과 별도로 붙을 수 있습니다.
• 로컬 CLI 메시지와 클라우드 작업이 같은 요금제 한도를 나눠 씁니다. 클라우드 작업을 따로 세지 않아요.
• 메시지 하나의 무게는 모델, 컨텍스트, 추론, 도구 사용, 검색, 캐싱이 모두 영향을 줍니다. 작은 스크립트나 간단한 함수는 한도의 일부만 쓰지만, 큰 프로젝트·오래 도는 작업·컨텍스트가 큰 긴 세션은 메시지당 훨씬 많이 씁니다.

한도를 다 써도 작업이 그 자리에서 끊기지는 않습니다. 진행 중인 턴에서 한도에 닿으면 공정 사용 범위 안에서 그 턴은 마저 진행할 수 있어요. 그 뒤에는 창이 초기화될 때까지 기다리거나, Plus·Pro라면 추가 크레딧을 살 수 있습니다.

그래서 저는 “메시지 몇 개 남았나”보다 “한 번에 얼마나 싣나”를 보는 게 맞다고 생각합니다. 실제로 얼마나 싣는지 재 봤어요.

요청 하나가 싣는 양을 재 보니

codex exec --json의 마지막 turn.completed 이벤트에 그 요청이 쓴 토큰이 나옵니다. 가장 짧은 요청부터 봤습니다.

$ codex exec --json "Reply with exactly: ok"
…
{"type":"turn.completed","usage":{"input_tokens":21300,"cached_input_tokens":7296,"cache_write_input_tokens":0,"output_tokens":5,"reasoning_output_tokens":0}}

“ok” 한 단어에 입력이 2만 1천 토큰입니다. 이어서 2만 8,921줄짜리 로그가 든 예제 폴더에서 네 가지 요청을 차례로 실행했습니다.

요청	입력 토큰(그중 캐시)	셸 명령
“ok” 한 단어	21,285 (7,296)	0
같은 요청, 400줄짜리 AGENTS.md(64KB) 있는 폴더	29,038 (0)	0
로그 파일을 주고 마지막 작업이 왜 실패했는지 묻기	88,393 (64,896)	3
로그 끝 50줄만 표준 입력으로 넘기고 같은 질문	22,647 (0)	0

로그를 통째로 맡기면 88,393토큰, 필요한 50줄만 넘기면 22,647토큰으로 같은 답을 얻었습니다. 통째로 맡기면 Codex가 rg·Select-String·Get-Content로 로그를 세 번 뒤졌고, 그때마다 대화 전체가 다시 실렸어요. 표준 입력으로 넘긴 내용은 지시 뒤에 <stdin> 블록으로 붙습니다.

네 요청 전후로 앱 서버에서 읽은 한도는 이렇게 바뀌었습니다.

창	네 요청 전	네 요청 후
5시간 창	53%	55%
주간 창	54%	54%

5시간 창은 2%포인트 올랐고 주간 창은 정수 단위에서 그대로였습니다. 사용률이 정수로만 나오고 요청마다 무게가 달라서 “요청 하나에 몇 %“로 일반화할 수는 없어요. 짧은 작업 몇 번으로는 창이 크게 움직이지 않고, 큰 컨텍스트와 도구 왕복이 한도를 빨리 줄인다는 방향만은 공식 설명과 맞았습니다.

싣는 걸 줄이는 법

공식 가격 문서가 권하는 방법에 위 측정을 붙여 보면 이렇습니다.

• 필요한 파일과 범위만 주세요. 로그 예에서 끝 50줄만 넘기자 입력이 약 4분의 1이 됐습니다.
• 지시는 정확하게 씁니다. 원하는 결과의 대상·형식·길이를 정하고, 꼭 필요한 일과 있으면 좋은 일을 나눠 주세요.
• AGENTS.md를 작게 유지합니다. 400줄짜리 파일은 요청마다 약 7,700토큰(21,285 → 29,038)을 더했어요. 폴더별로 나누는 것이 권장 방법입니다.
• 쓰지 않는 MCP 서버를 끕니다. MCP 서버마다 메시지에 컨텍스트가 더해져 한도를 더 씁니다.

같은 원리를 Claude Code에서 잰 결과는 Claude Code 토큰 절약 방법을 직접 잰 글에 있습니다. 두 도구 모두 “요청에 싣는 컨텍스트 × 도구 왕복 횟수”만큼 사용량이 늘어나요.

AGENTS.md가 205번에서 잘렸다

해 보니 여기서 예상과 달랐습니다. 규칙 400개를 담은 64KB짜리 AGENTS.md를 두고 “보이는 규칙 번호 중 가장 큰 것”을 물었더니 205라고 답하더라고요. 파일에는 400번까지 있었고, 경고나 오류는 없었습니다.

Codex CLI 0.158.0이었고, project_doc_max_bytes를 따로 두지 않은 상태였어요. 파일의 32,768바이트 지점이 205번 규칙 중간이었습니다.

지시 파일을 합치다가 전체 크기가 project_doc_max_bytes(기본 32KiB)에 닿으면 더 넣지 않는 규칙이 있습니다. 이번 결과를 보면 파일 하나가 한도를 넘을 때 그 파일도 한도 지점에서 잘려요. 늘어난 입력 토큰이 약 7,700개로 64KB 전체가 아니라 절반 정도만 실린 것과도 맞습니다.

중요한 규칙은 앞에 두고, 하위 폴더의 AGENTS.md로 나누세요. 한 파일에 꼭 둬야 한다면 config.toml의 project_doc_max_bytes로 한도를 올릴 수 있지만, 그만큼 요청마다 사용량도 늘어납니다. 설정 파일 위치와 문법은 Codex CLI config.toml 설정과 우선순위에 있어요.

마치며

재 보기 전에는 한도를 “몇 번 물어볼 수 있나”로 생각하기 쉬운데, 숫자를 보니 무엇을 얼마나 싣느냐가 훨씬 컸습니다. 같은 답을 얻는 데 로그를 통째로 주면 88,393토큰, 끝 50줄만 주면 22,647토큰이었으니까요. 길게 키운 AGENTS.md는 요청마다 비용을 더하면서 뒷부분은 조용히 잘리기까지 했고요.

지금 Codex 대화 화면에서 /status를 한 번 입력해 두 창의 남은 양과 리셋 시각을 확인해 보세요. 한도를 아끼려면 지시 파일부터 줄이는 게 빠르니, CLAUDE.md·AGENTS.md·GEMINI.md를 하나로 합치는 법을 이어서 보시면 좋습니다.

Claude Code도 5시간 창과 주간 창을 함께 쓰는 구조는 비슷하지만 세는 방식과 수치는 달라서, 그쪽은 Claude Code 사용량 한도가 계산되는 방식에 따로 정리했어요.

codex exec를 스크립트에서 돌린다면 표준 입력 대기와 한글 깨짐 문제를 Windows에서 AI CLI 한글이 깨질 때에서 먼저 확인하세요.