codex-usage
로그인된 Codex CLI 계정의 5시간·주간 사용률과 리셋 시각을 auth.json 토큰으로 조회(codex 실행 불요, Windows 동일)하고 --max 게이트로 활용
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 쪽 응답 구조가 바뀌면 조회가 실패할 수 있습니다. 그때는 조용히 넘기지 않고 "응답 형식이 바뀌었다"고 알려 줍니다.
- 사용량을 조회만 합니다. 한도를 늘리거나 플랜을 바꾸지 않습니다.
- 과거 이력·추세는 다루지 않습니다. 현재 시점의 값만 봅니다.