So sánh công cụ theo dõi chi phí Claude Code

Một công cụ theo dõi chi phí Claude Code thực sự đọc gì

Mỗi công cụ theo dõi chi phí Claude Code đọc một trong ba nguồn dữ liệu, và nguồn dữ liệu quyết định nó có thể trả lời câu hỏi nào. Bộ phân tích log đọc các file transcript của session trên chính disk của bạn. Dashboard đọc các bản ghi usage mà Anthropic lưu cho account hoặc tổ chức của bạn. Backend metrics đọc stream OpenTelemetry (OTel) do Claude Code phát ra khi bạn bật tính năng này. Cả ba có thể đồng thời đúng nhưng vẫn cho kết quả khác nhau, vì chúng đang đếm những thứ khác nhau.

Hướng dẫn này không giải thích lại token. cách Claude Code tính usage token giải thích input, output, cache writes và cache reads; bạn cần hiểu rõ phần đó trước khi xem dashboard. Nội dung ở đây hẹp hơn: với mỗi loại công cụ, nó nhìn thấy gì và không bao giờ nhìn thấy được gì.

Vì sao có 3 công cụ theo dõi chi phí Claude Code xuất hiện trong cùng một ngày

3 công cụ theo dõi chi phí Claude Code riêng biệt được đăng trong cùng một ngày. Chúng không phải là 3 phiên bản của cùng một công cụ, và đây mới là điểm hữu ích. Một công cụ phân tích các file session cục bộ. Một công cụ bọc các màn hình hiển thị mức sử dụng của tài khoản. Công cụ còn lại là một backend tracing được host mà bạn tự vận hành.

Chúng xuất hiện cùng lúc vì chi phí của một session agent không còn dễ nhận biết. Một chat thường có chi phí gần với mức bạn nhìn thấy trên màn hình. Agent đọc 20 file, chạy test suite và gửi lại toàn bộ cuộc hội thoại trong mỗi lượt, nên hóa đơn bị chi phối bởi phần context mà bạn không trực tiếp nhập. Với gói subscription, hoàn toàn không có con số đô la; chỉ có một thanh usage, và thanh này cạn nhanh hơn vào một số ngày. Mỗi công cụ trong 3 công cụ này giải quyết một phần khác nhau của khoảng trống đó.

Hình thức 1: parser log cục bộ cho biết hôm nay bạn đã dùng bao nhiêu

Claude Code lưu mỗi cuộc trò chuyện dưới dạng JSON Lines (JSONL) tại ~/.claude/projects/<project>/<session-id>.jsonl, trong đó <project> là đường dẫn thư mục làm việc với các ký tự không phải chữ và số được thay bằng -. Mỗi lượt phản hồi của assistant trong file đó đều có số token của request. Parser log cộng các số này lại và tính chi phí.

ccusage là lựa chọn mà hầu hết mọi người dùng. Công cụ này không cần cài đặt:

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

daily tính tổng theo ngày. --breakdown tách từng dòng theo model, nhờ đó bạn biết được một buổi chiều dùng Opus chiếm phần lớn chi phí cả tuần. blocks nhóm theo khung 5 giờ mà subscription reset. session tính tổng theo từng cuộc trò chuyện, còn --instances nhóm theo project để bạn thấy repository nào tốn kém. Thêm --since và --until để giới hạn khoảng thời gian, rồi chạy npx ccusage@latest daily --help để xem định dạng ngày mà version của bạn yêu cầu. Tính đến August 2026, công cụ này cũng đọc được log của các agent CLI khác, gồm Codex và OpenCode. Điều này hữu ích khi bạn muốn so sánh chúng.

Giá lấy từ bảng giá của model, và công cụ có 3 chế độ tính chi phí. --mode auto dùng giá trị costUSD mà Claude Code đã ghi vào file nếu giá trị này tồn tại, rồi tính từ số token nếu không có. --mode calculate luôn tính từ token và bỏ qua chi phí đã được ghi. --mode display chỉ hiển thị chi phí đã ghi và in $0.00 cho những dòng không có chi phí. Nếu tổng có vẻ không đúng, hãy chạy cùng một report với calculate rồi chạy lại với display. Chênh lệch lớn giữa hai kết quả có nghĩa là phần lớn entry không có chi phí được ghi, nên mọi con số bạn đang xem đều là ước tính.

Bạn cũng có thể dùng cùng dữ liệu này cho prompt. ccusage statusline in một dòng ngắn gọn cho status bar của Claude Code, được cấu hình trong ~/.claude/settings.json như mọi command status line khác. Xem xây dựng statusline cho Claude Code để biết block cấu hình và các field mà nó nhận.

Parser log không thể thấy những gì không xảy ra trên máy này. Laptop thứ hai, session trên claude.ai hoặc công việc của một đồng đội đều nằm trong transcript trên các máy tương ứng. Dữ liệu cũ cũng có thể đã mất, vì transcript mặc định được dọn sau 30 ngày theo cấu hình cleanupPeriodDays. Do đó, dữ liệu của quý trước sẽ không còn nếu bạn không archive.

Còn một rủi ro khác, liên quan đến cấu trúc dữ liệu. Tài liệu của Anthropic nêu rằng format của entry là phần nội bộ của Claude Code và thay đổi giữa các version. Vì vậy, script parse trực tiếp các file này có thể hỏng sau bất kỳ lần release nào. Điều này áp dụng cho mọi công cụ cùng loại. Đây cũng là lý do một dòng lệnh jq tự viết để xử lý JSONL thường tệ hơn vẻ ngoài: các parser được duy trì sẽ theo kịp thay đổi format, còn one-liner của bạn sẽ báo một con số sai nhưng trông rất đáng tin vào ngày một field bị đổi tên.

Cuối cùng, con số tính bằng dollar cần có một lưu ý khi bạn dùng subscription. Bạn không bị tính phí theo token trên Pro hoặc Max, nên con số này là chi phí mà số token của bạn sẽ tạo ra theo giá niêm yết của API. Nó đo mức độ sử dụng của bạn. Nó không phải hóa đơn thực tế. Nếu câu hỏi thực sự là nên dùng plan nào, đó là một bài toán riêng: xem đối chiếu billing API với subscription Claude.

Cách 2: màn hình usage tích hợp cho biết model nào đã tiêu tốn ngân sách

Claude Code có sẵn tính năng báo cáo nhưng hầu hết mọi người không bao giờ mở. Chạy /usage trong một session. Khối Session ở đầu màn hình hiển thị số token theo từng model và chi phí bằng dollar của session hiện tại. Giá trị này được tính cục bộ từ số token theo mức giá niêm yết tiêu chuẩn. Giá trị đó không phản ánh discount hoặc giá khuyến mại, nên có thể khác với hóa đơn của bạn. Tổng số liệu được reset khi /clear bắt đầu một cuộc hội thoại mới.

Với gói Pro, Max, Team hoặc Enterprise, màn hình này còn hiển thị bạn đã dùng bao nhiêu trong giới hạn của gói. Màn hình cũng phân bổ usage gần đây cho skills, subagents, plugins và từng MCP server dưới dạng phần trăm trên tổng usage. Màn hình đánh dấu các hành vi chiếm từ 10% usage gần đây trở lên, chẳng hạn context dài hoặc cache miss. Nhấn d hoặc w để chuyển giữa 24 giờ gần nhất và 7 ngày gần nhất. Các số liệu này là giá trị xấp xỉ và được tính từ lịch sử session cục bộ trên máy này, nên không tính thiết bị thứ hai. Khi thanh này trống thay vì chỉ ở mức thấp, màn hình cho biết window đã đóng nhưng không cho biết cách tiếp tục làm việc. cách xử lý sau khi bạn đã chạm giới hạn là một quyết định riêng về model, context và gói dịch vụ.

Khi có nhiều hơn một developer, các số liệu được chuyển lên cấp account. Một API organisation có trang usage trong Console, dashboard Claude Code hiển thị chi phí và số dòng code được chấp nhận theo từng thành viên, cùng Claude Code Analytics API trả về các metric hằng ngày theo từng user bằng admin key. Gói Team và Enterprise có báo cáo chi phí trong admin console, hỗ trợ export CSV và được cập nhật hằng ngày. Enterprise còn có analytics API. Bạn thấy những mục nào phụ thuộc vào cách từng developer đăng nhập, nên một organisation hỗn hợp phải đọc hai báo cáo rồi tự cộng số liệu.

Để lập ngân sách, số liệu được công bố trong tài liệu chi phí của Anthropic tính đến tháng 8 năm 2026 là trung bình gần $13 cho mỗi developer trong một ngày active và $150 đến $250 cho mỗi developer mỗi tháng; 90% user có chi phí dưới $30 mỗi ngày active. Hãy xem đây là benchmark được công bố từ các môi trường enterprise, không phải dự báo cho team của bạn. Hãy chạy pilot với một nhóm nhỏ và đo lường trước khi ngoại suy.

Dashboard không thể cho biết thông tin chi tiết hơn theo ngày và theo người. Chúng có thể cho bạn biết Opus được dùng nhiều nhất vào thứ Ba. Nhưng chúng không cho biết prompt nào, repository nào hoặc CI job nào đã sử dụng nó. Chúng cũng có độ trễ vì báo cáo của organisation được cập nhật hằng ngày. Do đó, chúng phù hợp để review hơn là phát hiện một agent chạy vượt kiểm soát trong buổi chiều hôm đó. Muốn phát hiện agent chạy vượt kiểm soát cần có limit, không phải báo cáo. Nội dung này được trình bày trong cách giới hạn chi phí agent trên VPS.

Dạng 3: tự xây dựng stack OpenTelemetry để biết prompt nào bị regression

Claude Code phát các metric và event OpenTelemetry sau khi bạn đặt một biến môi trường. Đây là lựa chọn duy nhất có thể stream dữ liệu token và chi phí theo từng user vào một hệ thống do bạn kiểm soát, gần như theo thời gian thực. Các metric này gồm claude_code.cost.usage tính bằng USD, claude_code.token.usage tính bằng token, claude_code.session.count và claude_code.active_time.total.

Metric token đáng chú ý vì các attribute của nó. Mỗi data point chứa type, có thể là input, output, cacheRead hoặc cacheCreation, cùng với model và query_source, có thể là main, subagent hoặc auxiliary. Nó cũng chứa agent.name, skill.name, mcp_server.name và mcp_tool.name. Như vậy là đủ để trả lời những câu hỏi mà không dashboard nào trả lời được: subagent chiếm bao nhiêu trong hóa đơn thay vì các lượt tương tác của chính bạn, một MCP server có làm số input token tăng gấp đôi không, việc ai đó sửa CLAUDE.md có làm số lần đọc cache giảm mạnh không. Hành vi của cache thường là nơi phát sinh bất ngờ, và khi nào prompt caching bắt đầu có lợi giải thích cách đọc các dữ liệu này.

Có một điểm cần đính chính vì nó xuất hiện trong mọi thread về chủ đề này. Langfuse là tracing backend self-hosted tốt, và cách chạy nó trên VPS được trình bày trong tự host Langfuse để tracing agent. OTLP endpoint của Langfuse chỉ nhận trace. Claude Code export metric và log event, không export span, nên trỏ OTEL_EXPORTER_OTLP_ENDPOINT đến Langfuse sẽ khiến project trống và không cung cấp lỗi hữu ích nào để đọc. Langfuse phù hợp với các agent bạn tự xây dựng trên API, trong đó code của bạn tạo từng span cùng prompt, model và chi phí của nó. Với Claude Code CLI, metrics store mới là lựa chọn phù hợp.

Thiết lập theo dõi chi phí Claude Code trên VPS của bạn

Chỉ cần 2 service: một collector để nhận metrics và Prometheus để lưu chúng. Không cho cả hai truy cập từ Internet công cộng, vì một cổng OTLP mở sẽ chấp nhận dữ liệu ghi từ bất kỳ ai tìm thấy nó. Ghi /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 là địa chỉ của server bên trong tunnel WireGuard, nên collector chỉ có thể được truy cập từ các máy của bạn. Địa chỉ đứng trước port rất quan trọng ở đây, vì các port Docker publish không bị ufw lọc: xem vì sao port Docker publish bypass ufw. Cách thiết lập tunnel được mô tả trong VPN WireGuard trên VPS của bạn.

/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 không bao giờ được publish ra host, vì Prometheus truy cập collector qua Compose network bằng service name:

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

Log của collector phải kết thúc bằng Everything is ready. Begin running and processing data.. Nếu log dừng vì lỗi cấu hình, YAML không được parse và container sẽ restart liên tục.

Bây giờ trỏ Claude Code vào collector. Trên mỗi máy chạy Claude Code, thêm nội dung sau vào ~/.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"
  }
}

Bắt đầu một session, gửi một prompt, chờ đến export interval (10 giây ở đây, mặc định là 60 giây), rồi hỏi Prometheus xem nó đã nhận được gì:

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

Bạn sẽ nhận được một số tên bắt đầu bằng claude_code_. Exporter đổi dấu chấm thành dấu gạch dưới và thêm unit, nên chuỗi chính xác phụ thuộc vào phiên bản collector của bạn. Kết quả rỗng nghĩa là chưa có dữ liệu nào đến. Kiểm tra protocol và port có khớp nhau không, vì http/protobuf dùng port 4318 còn grpc dùng port 4317; nếu không khớp thì lỗi xảy ra mà không có thông báo rõ ràng. Chạy claude --debug để xem debug log báo lỗi export OTel.

Nếu chỉ dùng một máy và không có server, hãy bỏ qua toàn bộ phần trên. Đặt OTEL_METRICS_EXPORTER=prometheus, rồi Claude Code sẽ tự cung cấp scrape endpoint tại http://localhost:9464/metrics. Khi prometheus là exporter duy nhất được liệt kê, Claude Code bỏ USD, tokens và s khỏi tên metric để scrape vẫn đúng định dạng văn bản Prometheus.

Mô hình này có một quyết định về quyền riêng tư. Theo mặc định, chỉ các số đếm rời khỏi máy; không có nội dung prompt hoặc output của tool. OTEL_LOG_USER_PROMPTS=1 và OTEL_LOG_TOOL_CONTENT=1 sẽ thay đổi điều đó, khiến metrics box của bạn chứa source code và mọi dữ liệu khác có trong context. Chỉ bật các tùy chọn này khi thực sự cần, và đọc cách giữ secret khỏi agent context trước.

Theo dõi chi phí cho các lần chạy bằng script và CI

Các lần chạy không tương tác thường gây bất ngờ vì không có ai theo dõi màn hình. claude -p cùng với --output-format json báo cáo chi phí của lần chạy đó trong payload kết quả:

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

Payload chứa total_cost_usd cùng với phần phân tích theo từng model, vì vậy một CI job có thể tự ghi lại chi phí mà không cần dashboard. Ghi thêm giá trị này vào một file hoặc đẩy nó dưới dạng metric đến collector ở trên. Đây là cách theo dõi chi phí hữu ích với mức chi phí thấp nhất, và chỉ tốn một lần gọi jq cho mỗi lần chạy.

Các trường hợp lỗi và dấu hiệu nhận biết

Báo cáo trống. npx ccusage@latest daily không in ra dòng nào nghĩa là nó không đọc đúng nơi Claude Code ghi dữ liệu. CLAUDE_CONFIG_DIR thay đổi vị trí đó, và parser phải được cấu hình để biết vị trí mới. Nếu có dữ liệu nhưng chỉ dừng ở khoảng một tháng trước, đó là cleanupPeriodDays đang hoạt động đúng thiết kế: transcript mặc định bị xóa sau 30 ngày.

Hai máy báo tổng số khác nhau. Đây là hành vi bình thường, không phải lỗi. Cả /usage và mọi log parser đều chỉ đọc lịch sử session cục bộ, nên usage từ thiết bị khác hoặc từ claude.ai đều không xuất hiện trên cả hai máy.

Tổng cục bộ không khớp với hóa đơn. Các số liệu cục bộ được tính từ số token theo bảng giá niêm yết tiêu chuẩn. Chúng không biết về giá khuyến mãi hoặc mức chiết khấu theo hợp đồng. Với gói subscription, token cũng không được tính phí riêng lẻ. Trang usage trong Console là nguồn chính thức cho việc tính phí API.

Chi phí tăng dù bạn vẫn làm cùng một việc. Trước hết, hãy kiểm tra các cột cache. Một session dài gửi lại toàn bộ history trong mỗi lượt, tính theo mức giá cached khi cache còn warm và theo mức giá input đầy đủ khi cache đã cold. Vì vậy, chỉ một khoảng nghỉ dài cũng khiến toàn bộ conversation được xử lý lại. Trường hợp này thể hiện bằng số input lớn đi kèm số output nhỏ. Giá token input so với output giải thích vì sao hai loại này thay đổi độc lập.

Một ngày có subagent trông như không thể xảy ra. Mỗi subagent chạy trong context window riêng, nên mức sử dụng token tăng theo số lượng subagent đã chạy và thời gian chạy của từng subagent. Chỉ dữ liệu OTel mới tách được chúng, thông qua attribute query_source trên claude_code.token.usage. Log parser chỉ hiển thị tổng số và không cho biết chi tiết.

FAQ

ccusage có hiển thị đúng số tiền tôi bị tính trong gói Max không?

Không. Với gói subscription, bạn không bị tính phí theo token. Vì vậy, log parser sẽ định giá token theo mức giá niêm yết tiêu chuẩn của API và hiển thị số tiền mà cùng khối lượng công việc đó sẽ tốn nếu thực hiện qua API. Đây là thước đo tương đối tốt để biết một ngày sử dụng nhiều đến mức nào. Nó cũng hữu ích khi so sánh các project hoặc model với nhau. Để biết số tiền thực tế phải trả, trang Console usage hiển thị phí API, còn trang billing của gói hiển thị phí subscription.

Claude Code lưu các file session mà những tool này đọc ở đâu?

Trong ~/.claude/projects/<project>/<session-id>.jsonl, trong đó <project> là đường dẫn working directory với các ký tự không phải chữ và số được thay bằng -. Mỗi dòng là một JSON object cho một message, lần dùng tool hoặc mục metadata. CLAUDE_CONFIG_DIR di chuyển toàn bộ directory. cleanupPeriodDays trong settings.json kiểm soát thời gian lưu giữ 30-day. Anthropic mô tả format của entry là nội bộ và có thể thay đổi giữa các version. Vì vậy, hãy parse bằng một tool được duy trì thay vì dùng script tự viết.

Tôi có thể gửi telemetry của Claude Code đến Langfuse không?

Không trực tiếp. OTLP endpoint của Langfuse nhận trace, còn Claude Code export metric và log event thay vì span, nên không có nơi để dữ liệu đổ vào. Hãy gửi metric của Claude Code đến một OpenTelemetry collector và lưu chúng trong Prometheus. Dùng Langfuse cho các agent do bạn tự xây dựng trên API, nơi code của bạn phát ra các span chứa prompt, model và chi phí.

Tại sao các con số trên máy local không khớp với trang Console usage?

Vì chúng được tính theo cách khác nhau. /usage và log parser cộng các token count từ các file session trên máy bạn đang sử dụng, rồi định giá chúng theo mức giá niêm yết tiêu chuẩn. Console báo cáo số tiền tổ chức của bạn thực sự bị tính, trên tất cả máy và tất cả key, sau khi áp dụng mọi khoản giảm giá. Chênh lệch là bình thường. Chênh lệch rất lớn thường có nghĩa là một thiết bị khác, một CI runner hoặc thành viên khác trong team đang tính phí vào cùng account.

Làm thế nào để theo dõi chi phí của một lần chạy claude -p trong CI?

Chạy bằng --output-format json và đọc total_cost_usd từ kết quả, chẳng hạn bằng claude -p "..." --output-format json | jq '.total_cost_usd'. Payload tương tự cũng chứa breakdown theo từng model và session ID. Ghi lại giá trị đó cho từng job để có chi phí theo từng pipeline mà không cần agent, dashboard hoặc service bổ sung.