Claude Code: jak monitorować koszty i zużycie tokenów

Co faktycznie odczytuje narzędzie do śledzenia wydatków Claude Code

Każde narzędzie do śledzenia wydatków Claude Code odczytuje jedno z trzech źródeł danych, a wybór źródła determinuje zakres pytań, na które można uzyskać odpowiedź. Parser logów odczytuje pliki transkrypcji sesji zapisane na lokalnym dysku. Panel kontrolny odczytuje rejestry użycia przechowywane przez Anthropic dla danego konta lub organizacji. Backend metryk odczytuje strumień OpenTelemetry (OTel), który Claude Code emituje po uruchomieniu. Wszystkie trzy źródła mogą być poprawne w tym samym czasie, a mimo to wykazywać rozbieżności, ponieważ zliczają różne parametry.

Niniejszy przewodnik nie omawia ponownie kwestii tokenów. jak Claude Code zlicza użycie tokenów obejmuje dane wejściowe, wyjściowe, zapisy w pamięci podręcznej oraz odczyty z niej, a żaden panel kontrolny nie jest użyteczny, dopóki te kwestie nie zostaną wyjaśnione. Pytanie w tym miejscu jest węższe: co widzi każdy z rodzajów narzędzi, a czego nigdy nie jest w stanie zobaczyć.

Dlaczego jednego dnia pojawiły się trzy narzędzia do śledzenia wydatków Claude Code

Tego samego dnia opublikowano trzy niezależne narzędzia do śledzenia wydatków w Claude Code. Nie były to trzy wersje tego samego narzędzia, co stanowi o ich użyteczności. Pierwsze analizowało lokalne pliki sesji. Drugie stanowiło nakładkę na ekrany użycia konta. Trzecie było hostowanym backendem śledzącym, który uruchamia się samodzielnie.

Pojawiły się jednocześnie, ponieważ koszt sesji agenta przestał być oczywisty. Koszt czatu jest w przybliżeniu widoczny na ekranie. Agent odczytuje dwadzieścia plików, uruchamia zestaw testów i przy każdym kroku przesyła ponownie całą konwersję, więc rachunek jest generowany przez kontekst, którego użytkownik nigdy nie wpisał. W ramach subskrypcji nie ma żadnej kwoty w dolarach, a jedynie pasek użycia, który w niektóre dni wyczerpuje się szybciej niż w inne. Każde z tych trzech rozwiązań wypełnia inną część tej luki.

Forma 1: lokalny parser logów informuje o kosztach bieżącego dnia

Claude Code przechowuje każdą konwersację w formacie JSON Lines w ~/.claude/projects/<project>/<session-id>.jsonl, gdzie <project> to ścieżka do katalogu roboczego, w którym znaki niebędące alfanumerycznymi zastąpiono -. Każda odpowiedź asystenta w tym pliku zawiera liczbę tokenów dla danego żądania. Parser logów sumuje je i wycenia.

ccusage to rozwiązanie, z którego korzysta większość użytkowników. Nie wymaga instalacji:

npx ccusage@latest daily
npx ccusage@latest daily --breakdown
npx ccusage@latest blocks
npx ccusage@latest session --json

daily sumuje koszty według daty. --breakdown dzieli każdy wiersz według modelu, co pozwala ustalić, że jedno popołudnie z Opus stanowi większość kosztów tygodnia. blocks grupuje dane według pięciogodzinnego okna, w którym resetuje się subskrypcja. session sumuje koszty dla każdej konwersacji, a --instances grupuje je według projektu, co pozwala sprawdzić, które repozytorium generuje największe wydatki. Dodaj --since oraz --until, aby ograniczyć zakres, i uruchom npx ccusage@latest daily --help dla formatu daty oczekiwanego przez daną wersję. Według stanu na sierpień 2026 narzędzie odczytuje również dane z innych interfejsów CLI dla agentów, w tym Codex i OpenCode, co jest istotne przy ich porównywaniu.

Wycena pochodzi z tabeli cen modeli, a narzędzie obsługuje trzy tryby kosztów. --mode auto wykorzystuje wartość costUSD zapisaną przez Claude Code w pliku, jeśli jest ona dostępna, a w przeciwnym razie oblicza koszt na podstawie liczby tokenów. --mode calculate zawsze oblicza koszt na podstawie tokenów i ignoruje zarejestrowane wartości. --mode display wyświetla tylko zarejestrowane koszty i drukuje $0.00 dla wierszy, które ich nie posiadają. Jeśli suma wydaje się błędna, uruchom ten sam raport z flagą calculate, a następnie display. Duża różnica między nimi oznacza, że większość wpisów nie zawiera zarejestrowanego kosztu, więc wszystkie odczytywane dane są jedynie szacunkowe.

Te same dane mogą zasilać prompt. ccusage statusline drukuje kompaktową linię dla paska stanu Claude Code, podłączoną do ~/.claude/settings.json tak samo, jak każde inne polecenie paska stanu. Zobacz budowanie paska stanu Claude Code, aby uzyskać informacje o bloku ustawień i odbieranych polach.

Parser logów nie widzi zdarzeń, które nie miały miejsca na tej maszynie. Drugi laptop, sesja w claude.ai, praca członka zespołu: te transkrypcje znajdują się na innych dyskach. Brakuje również starych danych, ponieważ transkrypcje są domyślnie usuwane po 30 dniach zgodnie z ustawieniem cleanupPeriodDays, więc dane z poprzedniego kwartału przepadły, chyba że zostały zarchiwizowane.

Istnieje jeszcze jedno ryzyko o charakterze strukturalnym. Dokumentacja Anthropic wskazuje, że format wpisów jest wewnętrzny dla Claude Code i zmienia się między wersjami, więc skrypty parsujące te pliki bezpośrednio mogą przestać działać po każdej aktualizacji. Dotyczy to każdego narzędzia tego typu. Jest to również powód, dla którego samodzielnie napisany jednowierszowy skrypt jq przetwarzający JSONL jest gorszym pomysłem, niż się wydaje: utrzymywane parsery śledzą zmiany formatu za użytkownika, podczas gdy własny skrypt będzie raportował błędne dane z pełnym przekonaniem w dniu, w którym pole zostanie przemianowane.

Na koniec, kwota w dolarach wymaga zastrzeżenia w przypadku subskrypcji. W planach Pro lub Max nie obowiązuje rozliczenie za token, więc liczba ta wskazuje, ile tokeny kosztowałyby według cennika API. Mierzy ona intensywność wykorzystania zasobów. Nie jest to faktyczny rachunek. Jeśli rzeczywistym pytaniem jest wybór odpowiedniego planu, porównanie to stanowi osobne zagadnienie: zobacz rozliczenia API a subskrypcja Claude.

Forma 2: wbudowane ekrany użycia wskazują, który model wyczerpał budżet

Claude Code posiada własny system raportowania, z którego większość użytkowników nigdy nie korzysta. Uruchom /usage wewnątrz sesji. Blok Session u góry ekranu prezentuje liczbę tokenów w podziale na modele oraz kwotę w dolarach dla bieżącej sesji, obliczoną lokalnie na podstawie liczby tokenów według standardowych stawek cennikowych. Kwota ta nie uwzględnia rabatów ani cen promocyjnych, dlatego może różnić się od kwoty na fakturze. Sumy są resetowane, gdy /clear rozpoczyna nową konwersację.

W planach Pro, Max, Team oraz Enterprise ten sam ekran pokazuje stopień wykorzystania limitu planu i przypisuje niedawne użycie do umiejętności, subagentów, wtyczek oraz poszczególnych serwerów MCP jako procent całości. System oznacza zachowania, które odpowiadają za 10% lub więcej niedawnego użycia, takie jak długi kontekst lub nietrafienia w pamięci podręcznej (cache misses). Naciśnij d lub w, aby przełączać się między danymi z ostatnich 24 godzin a ostatnich 7 dni. Liczby te są przybliżone i obliczane na podstawie lokalnej historii sesji na danej maszynie, więc użycie na drugim urządzeniu nie jest wliczane. Gdy pasek jest pusty, a nie tylko na niskim poziomie, ekran informuje o zamknięciu okna, ale nie o tym, jak kontynuować pracę; kwestia co zrobić po osiągnięciu limitu jest odrębną decyzją dotyczącą modelu, kontekstu i planu.

W przypadku zespołów liczących więcej niż jednego programistę, dane przenoszą się na poziom konta. Organizacja korzystająca z API otrzymuje dostęp do strony użycia w konsoli, pulpitu nawigacyjnego Claude Code z informacjami o wydatkach i zaakceptowanych liniach kodu na członka, a także Claude Code Analytics API, które zwraca te same dzienne metryki w przeliczeniu na użytkownika przy użyciu klucza administratora. Plany Teams i Enterprise otrzymują raport wydatków w konsoli administratora z możliwością eksportu do CSV, aktualizowany codziennie, a plan Enterprise dodatkowo udostępnia API analityczne. To, który z tych widoków jest dostępny, zależy od sposobu logowania każdego programisty, więc w mieszanej organizacji należy odczytać dwa raporty i zsumować je ręcznie.

Przy szacowaniu budżetu, opublikowana wartość w dokumentacji kosztów Anthropic na sierpień 2026 r. wynosi średnio około 13 USD na programistę za aktywny dzień oraz od 150 USD do 250 USD na programistę miesięcznie, przy czym 90% użytkowników mieści się w kwocie poniżej 30 USD za aktywny dzień. Należy traktować to jako opublikowany punkt odniesienia z wdrożeń korporacyjnych, a nie jako prognozę dla własnego zespołu. Przed ekstrapolacją należy przeprowadzić grupę pilotażową i dokonać pomiarów.

Pulpity nawigacyjne nie widzą niczego poniżej poziomu dnia i osoby. Wskażą, że model Opus odpowiadał za większość użycia we wtorek. Nie wskażą jednak, który prompt, które repozytorium lub które zadanie CI było tego przyczyną. Raporty te mają również opóźnienie, ponieważ raporty organizacyjne aktualizowane są codziennie, więc stanowią narzędzie przeglądowe, a nie sposób na zatrzymanie niekontrolowanego agenta w czasie rzeczywistym. Zatrzymanie niekontrolowanego procesu wymaga limitów, a nie raportów, co jest tematem utrzymywania kosztów agenta w ryzach na VPS.

Wariant 3: własny stos OpenTelemetry pozwala zidentyfikować regresję promptu

Claude Code emituje metryki i zdarzenia OpenTelemetry po ustawieniu jednej zmiennej środowiskowej. Jest to jedyna opcja przesyłania danych o tokenach i kosztach w przeliczeniu na użytkownika do systemu pod własną kontrolą w czasie zbliżonym do rzeczywistego. Metryki obejmują claude_code.cost.usage w USD, claude_code.token.usage w tokenach, claude_code.session.count oraz claude_code.active_time.total.

Metryka tokenów jest szczególnie istotna ze względu na swoje atrybuty. Każdy punkt danych zawiera type, czyli input, output, cacheRead lub cacheCreation, a także model i query_source, czyli main, subagent lub auxiliary. Zawiera również agent.name, skill.name, mcp_server.name oraz mcp_tool.name. Dane te pozwalają odpowiedzieć na pytania, których nie obsłuży żaden pulpit nawigacyjny: jaka część rachunku przypada na subagenty, a jaka na własne interakcje, czy dany serwer MCP podwoił liczbę tokenów wejściowych oraz czy odczyty z pamięci podręcznej spadły po edycji pliku CLAUDE.md. Zachowanie pamięci podręcznej jest zazwyczaj źródłem nieoczekiwanych wyników, a kiedy prompt caching się opłaca wyjaśnia, na co należy zwrócić uwagę.

Warto dokonać jednego sprostowania, ponieważ kwestia ta pojawia się w każdej dyskusji na ten temat. Langfuse jest dobrym, samodzielnie hostowanym backendem do śledzenia (tracingu), a jego uruchomienie na VPS opisano w samodzielne hostowanie Langfuse do śledzenia agentów. Jego punkt końcowy OTLP akceptuje wyłącznie ślady (traces). Claude Code eksportuje metryki i zdarzenia dziennika, a nie zakresy (spans), więc skierowanie OTEL_EXPORTER_OTLP_ENDPOINT na Langfuse pozostawi projekt pusty i nie wygeneruje żadnego czytelnego błędu. Langfuse jest właściwym narzędziem dla agentów budowanych samodzielnie na bazie API, gdzie własny kod tworzy każdy zakres wraz z jego promptem, modelem i kosztem. W przypadku interfejsu wiersza poleceń Claude Code, odpowiednim rozwiązaniem jest magazyn metryk.

Konfiguracja śledzenia wydatków Claude Code na własnym VPS

Wystarczą dwie usługi: kolektor do odbierania metryk oraz Prometheus do ich przechowywania. Obie należy odizolować od publicznego Internetu, ponieważ otwarty port OTLP akceptuje zapisy od każdego, kto go odnajdzie. Utwórz /opt/ccmetrics/compose.yaml:

services:
  collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes:
      - ./collector.yaml:/etc/otel/config.yaml:ro
    ports:
      - "10.8.0.1:4318:4318"
    restart: unless-stopped
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports:
      - "127.0.0.1:9090:9090"
    restart: unless-stopped

volumes:
  prom-data:

10.8.0.1 to adres serwera wewnątrz tunelu WireGuard, dzięki czemu kolektor jest osiągalny z Twoich maszyn i znikąd indziej. Adres przed numerem portu pełni tu kluczową rolę, ponieważ opublikowane porty Docker nie są filtrowane przez ufw: zobacz dlaczego opublikowane porty Docker omijają ufw. Konfiguracja samego tunelu opisana jest w VPN WireGuard na własnym VPS.

/opt/ccmetrics/collector.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  prometheus:
    endpoint: 0.0.0.0:8889

service:
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [prometheus]

/opt/ccmetrics/prometheus.yml. Port 8889 nigdy nie jest publikowany na hoście, ponieważ Prometheus łączy się z kolektorem przez sieć Compose przy użyciu nazwy usługi:

global:
  scrape_interval: 30s

scrape_configs:
  - job_name: claude-code
    static_configs:
      - targets: ["collector:8889"]

cd /opt/ccmetrics
docker compose up -d
docker compose logs collector

Dziennik kolektora powinien kończyć się wpisem Everything is ready. Begin running and processing data.. Dziennik, który zatrzymuje się na błędzie konfiguracji, oznacza, że plik YAML nie został poprawnie przetworzony, a kontener będzie restartował się w pętli.

Teraz skieruj na niego Claude Code. Na każdej maszynie, na której uruchamiasz Claude Code, dodaj poniższy wpis do ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "none",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://10.8.0.1:4318",
    "OTEL_METRIC_EXPORT_INTERVAL": "10000"
  }
}

Rozpocznij sesję, wyślij jedno zapytanie, odczekaj czas interwału eksportu (tutaj 10 sekund, domyślnie 60 sekund), a następnie zapytaj Prometheusa, co zarejestrował:

curl -s http://localhost:9090/api/v1/label/__name__/values | grep -o 'claude_code[a-z_]*'

Powinieneś otrzymać kilka nazw rozpoczynających się od claude_code_. Eksporter zamienia kropki na podkreślniki i dodaje jednostkę, więc dokładne ciągi znaków zależą od wersji kolektora. Pusty wynik oznacza, że żadne dane nie dotarły. Sprawdź, czy protokół i port są zgodne, ponieważ http/protobuf korzysta z 4317, a grpc z 4318, a niedopasowanie powoduje cichą awarię. Uruchom claude --debug, a dziennik debugowania zgłosi błędy eksportu OTel.

W przypadku jednej maszyny i braku serwera, pomiń powyższe kroki. Ustaw OTEL_METRICS_EXPORTER=prometheus, a Claude Code udostępni punkt końcowy scrape pod adresem http://localhost:9464/metrics. Gdy prometheus jest jedynym wymienionym eksporterem, Claude Code pomija jednostki USD, tokens oraz s w nazwach metryk, aby wynik scrape pozostał w poprawnym formacie tekstowym Prometheus.

Z tym rozwiązaniem wiąże się jedna decyzja dotycząca prywatności. Domyślnie z maszyny wychodzą tylko liczniki, bez treści zapytań i wyników narzędzi. OTEL_LOG_USER_PROMPTS=1 oraz OTEL_LOG_TOOL_CONTENT=1 zmieniają to zachowanie, co sprawia, że Twój serwer metryk będzie przechowywał kod źródłowy oraz wszystko inne, co znajdowało się w kontekście. Włączaj te opcje świadomie i najpierw przeczytaj jak chronić sekrety przed kontekstem agenta.

Monitorowanie wydatków dla uruchomień skryptowych i CI

Uruchomienia nieinteraktywne często zaskakują użytkowników, ponieważ nikt nie obserwuje ekranu w czasie rzeczywistym. claude -p wraz z --output-format json raportuje koszt takiego uruchomienia w swoim ładunku wynikowym:

claude -p "summarise the failing tests" --output-format json | jq '.total_cost_usd'

Ładunek zawiera total_cost_usd oraz zestawienie kosztów dla poszczególnych modeli, dzięki czemu zadanie CI może zarejestrować własne wydatki bez konieczności korzystania z pulpitu nawigacyjnego. Wartość tę można dopisać do pliku lub przesłać jako metrykę do wspomnianego wcześniej kolektora. Jest to najtańsza dostępna metoda śledzenia wydatków, której koszt wynosi jedno wywołanie jq na uruchomienie.

Tryby awarii i ich objawy

Raport jest pusty. npx ccusage@latest daily brak danych wyjściowych oznacza, że narzędzie nie odczytuje plików z lokalizacji, w której zapisuje je Claude Code. CLAUDE_CONFIG_DIR zmienia tę lokalizację, o czym należy poinformować parser. Jeśli dane istnieją, ale kończą się około miesiąc temu, jest to działanie cleanupPeriodDays zgodnie z projektem: transkrypcje są domyślnie usuwane po 30 dniach.

Dwie maszyny raportują różne sumy. Jest to zachowanie oczekiwane, a nie błąd. Zarówno /usage, jak i każdy parser logów odczytują tylko lokalną historię sesji, więc użycie z innego urządzenia lub z poziomu claude.ai nie jest uwzględniane w żadnym z nich.

Lokalna suma nie zgadza się z fakturą. Wartości lokalne są obliczane na podstawie liczby tokenów według standardowych stawek cennikowych. Nie uwzględniają one cen promocyjnych ani wynegocjowanych rabatów, a w przypadku subskrypcji tokeny nie są rozliczane indywidualnie. Strona użycia w Console jest wiarygodnym źródłem informacji o rozliczeniach API.

Koszty wzrosły przy wykonywaniu tej samej pracy. Przede wszystkim sprawdź kolumny pamięci podręcznej (cache). Długa sesja przesyła całą swoją historię przy każdym kroku; jest ona wyceniana według stawki dla pamięci podręcznej, gdy ta jest aktywna, oraz według pełnej stawki wejściowej, gdy wygasa. Jedna długa przerwa powoduje ponowne przetworzenie całej konwersacji. Objawia się to jako wysoka liczba tokenów wejściowych przy niskiej liczbie tokenów wyjściowych, a różnice w wycenie tokenów wejściowych i wyjściowych wyjaśniają, dlaczego te dwie wartości zmieniają się niezależnie.

Dzień z użyciem subagentów wydaje się niemożliwy. Każdy subagent korzysta z własnego okna kontekstowego, więc zużycie tokenów skaluje się wraz z liczbą uruchomionych agentów oraz czasem trwania każdego z nich. Tylko dane OTel pozwalają na ich rozróżnienie za pomocą atrybutu query_source w claude_code.token.usage. Parser logów pokaże jedynie sumę, pozostawiając użytkownika w niepewności co do szczegółów.

FAQ

Czy ccusage pokazuje kwotę, którą faktycznie płacę w planie Max?

Nie. W ramach subskrypcji rozliczenie nie odbywa się za token, więc parser logów wycenia tokeny według standardowych stawek API i pokazuje, ile dana praca kosztowałaby przy użyciu API. Jest to dobry wskaźnik porównawczy obciążenia w danym dniu, przydatny do zestawiania projektów lub modeli między sobą. Informacje o faktycznych kosztach znajdują się na stronie Console w sekcji rozliczeń API oraz na stronie rozliczeń planu w przypadku subskrypcji.

Gdzie Claude Code przechowuje pliki sesji odczytywane przez te narzędzia?

W ~/.claude/projects/<project>/<session-id>.jsonl, gdzie <project> to ścieżka katalogu roboczego, w której znaki niebędące alfanumerycznymi zastąpiono -. Każda linia jest obiektem JSON reprezentującym pojedynczą wiadomość, użycie narzędzia lub wpis metadanych. CLAUDE_CONFIG_DIR przenosi cały katalog, a cleanupPeriodDays w settings.json zarządza 30-dniowym okresem przechowywania. Anthropic traktuje format wpisów jako wewnętrzny i podlegający zmianom między wersjami, dlatego należy analizować go za pomocą utrzymywanego narzędzia, a nie własnego skryptu.

Czy mogę wysyłać telemetrię Claude Code do Langfuse?

Nie bezpośrednio. Punkt końcowy Langfuse OTLP akceptuje ślady (traces), podczas gdy Claude Code eksportuje metryki i zdarzenia dziennika, a nie zakresy (spans), więc dane nie mają gdzie trafić. Metryki Claude Code należy wysyłać do kolektora OpenTelemetry i przechowywać w Prometheus. Langfuse należy stosować w przypadku agentów budowanych samodzielnie na bazie API, gdzie własny kod emituje zakresy zawierające prompt, model i koszt.

Dlaczego moje lokalne wyliczenia nie zgadzają się ze stroną użycia w Console?

Ponieważ są obliczane w inny sposób. /usage i parsery logów sumują liczbę tokenów z plików sesji na używanym komputerze, a następnie wyceniają je według standardowych stawek cennika. Console raportuje kwotę, którą faktycznie obciążono organizację, uwzględniając wszystkie urządzenia, wszystkie klucze oraz ewentualne rabaty. Rozbieżność jest zjawiskiem normalnym. Bardzo duża różnica zazwyczaj oznacza, że drugie urządzenie, runner CI lub inny członek zespołu generuje koszty w ramach tego samego konta.

Jak śledzić koszt uruchomienia claude -p w CI?

Należy uruchomić proces z flagą --output-format json i odczytać total_cost_usd z wyniku, na przykład za pomocą claude -p "..." --output-format json | jq '.total_cost_usd'. Ten sam ładunek danych zawiera zestawienie kosztów według modelu oraz identyfikator sesji. Rejestrując tę wartość dla każdego zadania, można uzyskać informację o wydatkach na potok (pipeline) bez konieczności używania agenta, panelu sterowania czy dodatkowych usług.