1. 시작하기
로그인 후 연결된 프로바이더에서 "키 등록"을 눌러 API 키를 붙여넣으면 끝입니다.
등록 즉시 최근 45일 사용량을 수집해 대시보드에 표시합니다.
2. 어떤 키를 넣어야 하나요?
OpenAI: 조직 Admin 키(sk-admin…)가 필요합니다.
platform.openai.com → Settings → Organization → Admin keys에서 발급하세요 (Read only 권한이면 충분).
모델 호출용 프로젝트 키(sk-proj…)로는 사용량 조회가 안 됩니다.
Anthropic: Admin 키(sk-ant-admin…)가 필요합니다.
platform.claude.com → Settings → Admin keys에서 발급하세요.
개인 계정은 Admin 키를 만들 수 없으니 조직 설정에서 Team 조직으로 전환해야 합니다.
3. 화면 읽는 법
프로바이더를 클릭하면 프로젝트(워크스페이스) → 모델 순으로 비용이 펼쳐집니다.
키를 여러 개 등록하면 조직별로도 나뉘어 보입니다.
금액은 프로바이더의 실제 청구 데이터 기준이며, 모델별 분해는 토큰×단가 근사를 실측 합계에 맞게 보정한 값입니다.
4. 갱신 주기
매일 03시(KST)에 자동 수집되고, "지금 갱신" 버튼으로 10분에 한 번 수동 갱신할 수 있습니다.
프로바이더 측 데이터 반영이 수 분~수 시간 지연될 수 있어 실시간은 아닙니다.
5. 예산 알림
상단에서 월 예산($)을 설정해두면, 이번 달 비용이 예산의 80%와 100%에 도달할 때
가입 이메일로 알림 메일이 발송됩니다 (각 1회, 매달 리셋).
6. 구독 사용량 연동 (Claude Code·Codex·Gemini CLI)
API가 아니라 구독으로 쓰는 AI의 토큰도 리더보드에 합산할 수 있습니다. 순서:
① 업로드 토큰 발급 — 헤더 내 계정 ▾ → 마이페이지 → 구독 사용량 연동 → [업로드 토큰 발급] 클릭.
tbu_로 시작하는 내 전용 토큰과, 토큰이 채워진 등록 명령이 표시됩니다.
② 터미널에서 등록 명령 실행 — 마이페이지의 [명령 복사]를 눌러 붙여넣으면 끝.
쓰는 CLI에 따라 명령 앞부분만 다릅니다:
claude mcp add tokenbill -- npx -y tokenbill-mcp@latest --token 내토큰
codex mcp add tokenbill -- npx -y tokenbill-mcp@latest --token 내토큰
gemini mcp add tokenbill -- npx -y tokenbill-mcp@latest --token 내토큰
③ 끝 — 이후 자동 — CLI를 실행할 때마다 최근 60일 사용량이 자동 업로드됩니다.
하나만 등록해도 PC의 세 CLI 기록을 전부 수집하며, AI에게 "내 토큰 순위 알려줘"라고 물으면 순위를 답해줍니다.
보너스 — 로컬 대화 뷰어: MCP를 연동해두면 Claude Code가 켜져 있는 동안
헤더 🧰 도구 ▾ → [🗂️ 대화 뷰어]로 과거 대화(입력·출력·도구 호출)를 열람·검색할 수 있습니다
— Claude Code·Codex·Gemini CLI에 Cursor까지 지원합니다.
같은 메뉴의 [🧩 스킬 관리]는 Claude Code가 공식적으로 읽는 스킬(개인 ~/.claude/skills · 프로젝트 .claude/skills · 플러그인)을 모아 보여주고,
프로젝트에만 있는 스킬을 어디서나 쓰도록 개인 폴더로 옮겨 주며,
[🔌 MCP 설정]은 등록된 MCP를 토큰을 가린 채 보여주고 다른 PC용 설정을 내보냅니다.
CLI가 꺼져 있을 땐 npx -y tokenbill-mcp@latest --viewer로 직접 실행하세요.
뷰어는 내 PC(127.0.0.1) 안에서만 로그를 읽으며 어떤 데이터도 업로드되지 않습니다.
토큰이 유출된 것 같으면 마이페이지에서 재발급하세요 (이전 토큰 즉시 무효).
구독 사용량은 본인 PC 로그 기반이라 프로바이더 표시에 🖥️가 붙고, 비용은 $0(정액 구독)으로 집계됩니다.
해당 AI의 로그인 이메일은 마스킹된 형태로만 표시·보관되어(원본 미저장),
계정을 여러 개 쓰는 경우 계정별로 사용량이 구분됩니다.
7. 문제가 있거나 아이디어가 있나요?
헤더의 피드백 버튼(또는 하단 "버그 신고·기능 제안")으로 알려주세요 —
지금 신고하기.
접수 내용은 공개 이슈 목록에 등록되어 처리 현황을 확인할 수 있습니다.
8. 키 보안
등록한 API 키는 서버에서 암호화되어 저장되며 화면에는 마스킹된 형태로만 표시됩니다.
해제하면 키와 수집된 데이터가 함께 삭제됩니다.