---
title: "codex-usage"
description: "이 머신에 로그인된 Codex CLI(ChatGPT 계정)의 사용량(5시간·주간 창 사용률, 리셋 시각, 플랜)을 ~/.codex/auth.json 토큰으로 직접 조회한다(codex 실행 불요, Windows 동일). \"codex 사용량 얼마나 남았어\", \"코덱스 한도 확인해줘\", \"codex 리셋 언제야\", \"지금 codex 돌려도 돼?\" 같은 요청과 codex 를 많이 쓰는 작업 앞 \"N% 이하일 때만\" 게이트(--max)에 사용한다. OpenAI API 키 과금은 대상이 아니다. [책임 경계] 본 스킬은 Codex CLI 구독 사용량 전담 — itda-dev-support:claude-usage 는 Claude Code 사용량."
pack: itda-dev-support
slug: codex-usage
status: experimental
tags: ["codex", "openai", "chatgpt", "usage", "quota", "rate-limit", "subscription", "devtools", "gate"]
---
# codex-usage 사용 가이드

지금 이 컴퓨터에 로그인된 **Codex CLI(ChatGPT 계정) 구독 사용량**이 얼마나 남았는지 알려줍니다. 5시간 창과 주간 창의 사용률, 리셋 시각, 플랜 이름을 한 번에 봅니다.

**Claude에게 말로 물으면 됩니다** — "codex 사용량 얼마나 남았어?" 한마디면 됩니다. Codex를 따로 띄우지 않아도 되고, 명령을 외울 필요도 없습니다.

> ⚠️ 이 가이드는 **ChatGPT 구독**(Plus·Pro 등)으로 쓰는 Codex CLI 사용량에 관한 것입니다. OpenAI **API 키** 과금은 대상이 아닙니다 — 그쪽은 platform.openai.com 대시보드에서 직접 보셔야 합니다.

---

## 무엇을 할 수 있나요

| 하고 싶은 것 | 이렇게 실행하세요 |
|--------------|-----------------|
| 지금 사용량 확인 | `/codex-usage 사용량 얼마나 남았어` |
| 리셋 시각 확인 | `/codex-usage codex 리셋 언제야` |
| 무거운 작업 전 안전 확인 | `/codex-usage 5시간 창이 20% 이하일 때만 알려줘` |
| 주간 기준으로 판단 | `/codex-usage 주간 창이 80% 넘었는지 봐줘` |

자연어로 "지금 codex 돌려도 돼?", "코덱스 한도 확인해줘"라고 말해도 같은 스킬이 동작합니다.

---

## 무엇을 보여주나요

조회하면 Claude가 다음을 한 줄로 정리해 말해 줍니다.

- **플랜** — Plus, Pro 등 현재 구독 등급
- **5시간 창** — 짧은 주기 한도의 사용률과 리셋 시각
- **7일 창** — 주간 한도의 사용률과 리셋 시각

80%를 넘긴 창이 있으면 Claude가 **그것부터 먼저** 말해 줍니다. 한도에 걸려 작업이 중간에 끊기는 일을 미리 피하기 위해서입니다.

---

## 무거운 작업 앞에 "안전장치"로 쓰기

Codex를 많이 돌리는 작업(대규모 코드 생성·긴 리뷰 세션)을 시작하기 전에 남은 한도를 먼저 확인해두면, 작업이 반쯤 진행된 상태에서 한도에 걸려 멈추는 상황을 막을 수 있습니다.

이렇게 말하세요:

```
/codex-usage 5시간 창이 30% 이하면 알려줘. 그때만 이 작업 codex 로 넘길게
```

기준을 넘어선 상태면 Claude가 **통과시키지 않고** 현재 사용률과 리셋까지 남은 시간을 알려 줍니다. 조회 자체가 실패한 경우에도 통과시키지 않습니다 — "모르는 상태"를 "괜찮은 상태"로 취급하지 않기 위해서입니다.

---

## 시작하기 전에 준비할 것

특별한 설정은 없습니다. **Codex CLI에 이미 로그인되어 있으면 그걸로 끝**입니다.

이 스킬은 Codex가 로그인할 때 남겨둔 `~/.codex/auth.json` 자격증명 파일을 그대로 읽습니다. 키체인은 쓰지 않으며, **Windows에서도 동일하게 동작**합니다.

Codex 프로그램을 실행할 필요가 없다는 점이 중요합니다 — 파일만 읽고 서버에 직접 물어보기 때문에, 조회가 빠르고 플랫폼을 가리지 않습니다. 인터넷 연결은 필요합니다.

---

## 안 될 때

| 증상 | 원인 / 해결 |
|------|-------------|
| "로그인되어 있지 않다"는 안내 (`no_credential`) | 이 컴퓨터에서 Codex CLI에 아직 로그인하지 않았습니다. Codex를 한 번 실행해 로그인하세요 |
| "자격증명 형식이 이상하다"는 안내 (`bad_credential`) | `~/.codex/auth.json` 내용이 손상됐거나 구조가 다릅니다. 다시 로그인해 파일을 새로 만드세요 |
| "자격증명이 만료됐다"는 안내 (`token_expired`) | 토큰 유효기간이 지났습니다. Codex를 한 번 실행하면 자동으로 갱신됩니다 |
| "응답 형식이 바뀌었다"는 안내 (`bad_response`) | OpenAI 쪽 응답 구조가 변경된 경우입니다. 스킬 갱신이 필요하니 제보해 주세요 |
| "네트워크 오류" 안내 (`network`) | 인터넷 연결 또는 방화벽 문제입니다 |

---

## 팁

- **리셋 시각을 함께 보세요.** 사용률이 높아도 곧 리셋이라면 잠깐 기다리는 쪽이 낫습니다.
- **5시간 창과 주간 창을 나눠 보세요.** 5시간 창만 찬 상태라면 몇 시간 뒤 재개하면 되지만, 주간 창이 찼다면 계획을 다시 짜야 합니다.
- **자격증명은 건드리지 않습니다.** 이 스킬은 읽기만 하며, 로그인·토큰 재발급을 대신 해주지 않습니다. 만료되면 안내만 합니다.
- **토큰 값은 절대 출력되지 않습니다.** 화면·로그·이슈 어디에도 남지 않도록 고정되어 있습니다.

---

## 이 스킬이 아닌 것

| 알고 싶은 것 | 어디로 |
|---|---|
| Claude Code 사용량 | `claude-usage` 스킬 |
| OpenAI API 키 과금 | platform.openai.com 대시보드에서 직접 |
| 메뉴 막대에 항상 띄우고 80%·100%에서 알림 받기 | sheriff 앱 (같은 데이터의 상주 버전) |

---

## 지금 버전의 범위와 한계

- ⚠️ **버전 0.1.0 (experimental)**: OpenAI 쪽 응답 구조가 바뀌면 조회가 실패할 수 있습니다. 그때는 조용히 넘기지 않고 "응답 형식이 바뀌었다"고 알려 줍니다.
- 사용량을 **조회**만 합니다. 한도를 늘리거나 플랜을 바꾸지 않습니다.
- 과거 이력·추세는 다루지 않습니다. 현재 시점의 값만 봅니다.