مقارنة أدوات تتبّع إنفاق Claude Code

ما الذي يقرأه متتبّع إنفاق Claude Code فعلياً

يقرأ كل متتبّع لإنفاق Claude Code أحد ثلاثة مصادر للبيانات، ويحدد المصدر السؤال الذي يمكنه الإجابة عنه. يقرأ محلّل السجلات ملفات نص الجلسات الموجودة على القرص الخاص بك. وتقرأ لوحة المعلومات سجلات الاستخدام التي تحتفظ بها Anthropic لحسابك أو مؤسستك. أما مكوّن خلفية المقاييس، فيقرأ تدفق OpenTelemetry (OTel) الذي يصدره Claude Code عند تفعيله. يمكن أن تكون المصادر الثلاثة صحيحة في الوقت نفسه، ومع ذلك تختلف نتائجها، لأنها تحسب أشياء مختلفة.

لا يعيد هذا الدليل شرح الرموز المميزة. يشرح كيفية احتساب Claude Code لاستخدام الرموز المميزة مدخلات الطلبات ومخرجاتها وكتابات ذاكرة التخزين المؤقت وقراءات ذاكرة التخزين المؤقت، ولن تكون أي لوحة معلومات مفيدة كثيراً قبل فهم ذلك الجزء. السؤال هنا أضيق نطاقاً: ما الذي يمكن لكل نوع من الأدوات رؤيته، وما الذي لا يمكنه رؤيته مطلقاً.

لماذا ظهرت 3 أدوات لتتبّع إنفاق Claude Code في يوم واحد

نُشرت 3 أدوات منفصلة لتتبّع إنفاق Claude Code في اليوم نفسه. لم تكن 3 إصدارات من الأداة نفسها، وهذه هي النقطة المفيدة. كانت إحداها تحلّل ملفات الجلسات المحلية. وكانت الثانية تغلّف شاشات استخدام الحساب. أما الثالثة فكانت خلفية لتتبّع العمليات مستضافةً يمكنك تشغيلها بنفسك.

ظهرت معاً لأن تكلفة جلسة الوكيل لم تعد واضحة. تبلغ تكلفة المحادثة تقريباً ما يمكنك رؤيته على الشاشة. لكن الوكيل يقرأ 20 ملفاً، ويشغّل مجموعة الاختبارات، ويعيد إرسال المحادثة كاملةً في كل دور، لذلك تحدد السياقات التي لم تكتبها بنفسك قيمة الفاتورة. في الاشتراك، لا يظهر أي مبلغ بالدولار، بل يظهر شريط استخدام فقط ينفد في بعض الأيام أسرع من أيام أخرى. وتسد كل أداة من الأدوات الثلاث جزءاً مختلفاً من هذه الفجوة.

الشكل 1: محلل سجلات محلي يوضح تكلفة استخدامك اليوم

يخزّن Claude Code كل محادثة بصيغة JSON Lines (JSONL) في ~/.claude/projects/<project>/<session-id>.jsonl، حيث إن <project> هو مسار دليل العمل بعد استبدال الأحرف غير الأبجدية الرقمية بـ -. يتضمن كل دور للمساعد في هذا الملف أعداد الرموز المميزة الخاصة بالطلب. يجمع محلل السجلات هذه الأعداد ويحسب تكلفتها.

يختار معظم المستخدمين ccusage. ولا يتطلب تثبيتاً:

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

يحسب daily الإجماليات حسب التاريخ. ويقسّم --breakdown كل صف حسب النموذج، وبذلك تعرف أن فترة بعد الظهر واحدة باستخدام Opus قد تمثل معظم استخدام الأسبوع. ويجمع blocks البيانات ضمن نافذة الخمس ساعات التي يُعاد فيها ضبط الاشتراك. ويحسب session الإجمالي لكل محادثة، بينما يجمع --instances البيانات حسب المشروع لتعرف أي مستودع أعلى تكلفة. أضف --since و--until لتحديد النطاق، وشغّل npx ccusage@latest daily --help لمعرفة تنسيق التاريخ الذي يتوقعه إصدارك. اعتباراً من August 2026، يقرأ أيضاً سجلات أدوات CLI أخرى للوكلاء، ومنها Codex وOpenCode، وهذا مهم عند مقارنتها.

تأتي الأسعار من جدول أسعار النماذج، وتوفّر الأداة ثلاثة أوضاع لحساب التكلفة. يستخدم --mode auto قيمة costUSD التي كتبها Claude Code في الملف عند توفرها، ويحسب التكلفة من أعداد الرموز المميزة عند عدم توفرها. يحسب --mode calculate التكلفة دائماً من أعداد الرموز المميزة ويتجاهل أي تكلفة مسجلة. يعرض --mode display التكاليف المسجلة فقط، ويطبع $0.00 للصفوف التي لا تحتوي على تكلفة مسجلة. إذا بدا أحد الإجماليات غير صحيح، فشغّل التقرير نفسه باستخدام calculate ثم باستخدام display. تعني الفجوة الكبيرة بين النتيجتين أن معظم الإدخالات لا تحتوي على تكلفة مسجلة، ولذلك فإن كل ما تقرؤه تقديري.

يمكن أيضاً استخدام البيانات نفسها في شريط الأوامر. يطبع ccusage statusline سطراً مختصراً لشريط حالة Claude Code، ويمكن ربطه في ~/.claude/settings.json مثل أي أمر آخر لسطر الحالة. راجع إنشاء سطر حالة في Claude Code لمعرفة كتلة الإعدادات والحقول التي يستقبلها.

لا يستطيع محلل السجلات رؤية أي شيء لم يحدث على هذا الجهاز. فالحاسوب المحمول الثاني، والجلسة على claude.ai، وعمل أحد أعضاء الفريق، كلها سجلات موجودة على أجهزتها. كما قد تكون البيانات القديمة مفقودة، لأن السجلات النصية تُنظَّف افتراضياً بعد 30 يوماً وفق إعداد cleanupPeriodDays، ولذلك ستختفي بيانات الربع السابق ما لم تكن قد أرشفتها.

هناك خطر آخر، وهو خطر بنيوي. تنص وثائق Anthropic على أن تنسيق الإدخالات داخلي في Claude Code ويتغير بين الإصدارات، ولذلك قد تتعطل البرامج النصية التي تحلل هذه الملفات مباشرة مع أي إصدار جديد. وينطبق ذلك على كل أداة من هذا النوع. ولهذا السبب أيضاً فإن كتابة سطر واحد يدوياً باستخدام jq لتحليل JSONL أسوأ مما تبدو عليه: فالمحللات التي تتم صيانتها تتابع تغييرات التنسيق نيابة عنك، بينما سيعرض سطر الأوامر الذي كتبته بنفسك رقماً خاطئاً بثقة في اليوم الذي يتغير فيه اسم أحد الحقول.

أخيراً، يحتاج الرقم بالدولار إلى توضيح عند استخدام اشتراك. لا تُحاسب لكل رمز مميز في Pro أو Max، ولذلك يوضح الرقم ما كانت رموزك المميزة ستكلفه وفق أسعار API المعلنة. وهو يقيس كثافة استخدامك، وليس قيمة فاتورتك. إذا كان السؤال الفعلي هو الخطة التي ينبغي اختيارها، فهذه مقارنة مستقلة: راجع الفوترة عبر API مقارنة باشتراك Claude.

النمط 2: تعرض شاشات الاستخدام المضمّنة النموذج الذي استهلك الميزانية

يأتي Claude Code مزوّداً بتقارير خاصة به، لكن معظم المستخدمين لا يفتحونها. شغّل /usage داخل جلسة. يعرض قسم Session في الأعلى عدد الرموز المميزة حسب النموذج، ومبلغاً بالدولار للجلسة الحالية، ويُحسَب محلياً من أعداد الرموز المميزة وفق أسعار القائمة القياسية. لا يعكس هذا المبلغ سعراً مخفّضاً أو ترويجياً، لذلك قد يختلف عن فاتورتك. تُصفّر الإجماليات عندما يبدأ /clear محادثة جديدة.

في خطط Pro وMax وTeam وEnterprise، تعرض الشاشة نفسها مقدار ما استخدمته من حد خطتك، وتنسب الاستخدام الأخير إلى المهارات والوكلاء الفرعيين والإضافات وخوادم MCP الفردية كنسبة مئوية من الإجمالي. وتحدّد السلوكيات التي تمثل 10% أو أكثر من الاستخدام الأخير، مثل السياق الطويل أو حالات فشل ذاكرة التخزين المؤقت. اضغط d أو w للتبديل بين آخر 24 ساعة وآخر 7 أيام. هذه الأرقام تقريبية، وتُحسَب من سجل الجلسات المحلي على هذا الجهاز، لذلك لا يُحتسب جهاز ثانٍ.

عندما يتجاوز الاستخدام مطوّراً واحداً، تنتقل الأرقام إلى مستوى الحساب. تحصل مؤسسة API على صفحة الاستخدام في Console، ولوحة Claude Code تعرض الإنفاق والأسطر المقبولة لكل عضو، وواجهة Claude Code Analytics API التي تعيد المقاييس اليومية نفسها لكل مستخدم باستخدام مفتاح إداري. وتحصل خطتا Teams وEnterprise على تقرير إنفاق في وحدة تحكم المسؤول مع إمكانية التصدير إلى CSV، ويُحدَّث يومياً، بينما تضيف Enterprise واجهة analytics API. يعتمد ما تراه على طريقة تسجيل دخول كل مطوّر، لذلك تقرأ المؤسسة المختلطة تقريرين وتجمعهما يدوياً.

لتقدير الميزانية، يبلغ الرقم المنشور في وثائق تكاليف Anthropic حتى August 2026 متوسطاً يقارب $13 لكل مطوّر في اليوم النشط، و$150 إلى $250 لكل مطوّر شهرياً، مع بقاء 90% من المستخدمين تحت $30 في اليوم النشط. تعامل مع ذلك على أنه معيار منشور من عمليات نشر مؤسسية، لا توقّعاً لفريقك. شغّل مجموعة تجريبية وقِس الاستخدام قبل التعميم.

لا تستطيع لوحات المعلومات رؤية أي شيء أدق من اليوم والمستخدم. ستخبرك بأن Opus استُخدم معظم يوم الثلاثاء. لكنها لن تخبرك بأي مطالبة، أو مستودع، أو مهمة CI تسببت في ذلك. كما أنها تتأخر، لأن تقارير المؤسسة تُحدَّث يومياً، ولذلك فهي أداة للمراجعة وليست وسيلة لاكتشاف وكيل منفلت بعد ظهر اليوم نفسه. يتطلب اكتشاف الوكيل المنفلت حدوداً، لا تقارير، وهذا هو موضوع ضبط تكاليف الوكيل ضمن حدود على VPS.

النهج 3: تخبرك حزمة OpenTelemetry الخاصة بك بأي prompt تراجع أداؤه

يُصدر Claude Code مقاييس وأحداث OpenTelemetry بعد ضبط متغير بيئة واحد، وهذا هو الخيار الوحيد الذي يبث بيانات الرموز المميزة والتكلفة لكل مستخدم إلى نظام تتحكم فيه، بوقت قريب من الفعلي. تشمل المقاييس claude_code.cost.usage بالدولار الأمريكي، وclaude_code.token.usage بالرموز المميزة، وclaude_code.session.count وclaude_code.active_time.total.

المقياس الأهم هو مقياس الرموز المميزة بسبب سماته. تحمل كل نقطة بيانات type، وهي input أو output أو cacheRead أو cacheCreation، إضافة إلى model وquery_source، وهي main أو subagent أو auxiliary. وتحمل أيضاً agent.name وskill.name وmcp_server.name وmcp_tool.name. يكفي ذلك للإجابة عن أسئلة لا يستطيع أي dashboard الوصول إليها: ما مقدار الفاتورة الناتج عن subagents بدلاً من أدوارك أنت، وهل ضاعف أحد خوادم MCP رموز الإدخال، وهل انهارت قراءات cache بعد أن عدّل شخص ما CLAUDE.md. غالباً ما يختبئ المفاجئ في سلوك cache، ويوضح متى تصبح prompt caching مجدية ما الذي تنظر إليه.

هناك تصحيح مهم ينبغي إجراؤه، لأنه يتكرر في كل نقاش حول هذا الموضوع. يُعد Langfuse backend جيداً للتتبّع الذاتي الاستضافة، وقد غطّت استضافة Langfuse ذاتياً لتتبّع الوكلاء تشغيله على VPS. تقبل نقطة نهاية OTLP الخاصة به traces فقط. يصدّر Claude Code metrics وlog events، وليس spans، لذلك يؤدي توجيه OTEL_EXPORTER_OTLP_ENDPOINT إلى Langfuse إلى بقاء المشروع فارغاً، ولن تحصل على أي خطأ مفيد لقراءته. Langfuse هو الأداة المناسبة للوكلاء الذين تبنيهم بنفسك باستخدام API، حيث ينشئ كودك كل span مع prompt وmodel وcost الخاصة به. أما بالنسبة إلى CLI الخاص بـClaude Code، فالمطابقة الصحيحة هي metrics store.

إعداد تتبّع إنفاق Claude Code على VPS الخاص بك

تكفي خدمتان: جامع لاستقبال المقاييس، وPrometheus لتخزينها. أبقِ الخدمتين بعيدتين عن الإنترنت العام، لأن منفذ OTLP المفتوح يقبل عمليات الكتابة من أي شخص يعثر عليه. اكتب /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 هو عنوان الخادم داخل نفق WireGuard، لذلك يمكن الوصول إلى الجامع من أجهزتك فقط، وليس من أي مكان آخر. العنوان الموجود قبل المنفذ مهم هنا فعلاً، لأن منافذ Docker المنشورة لا يرشّحها ufw: راجع سبب تجاوز منافذ Docker المنشورة لـ ufw. أما إعداد النفق نفسه فموضح في شبكة WireGuard VPN على 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. لا يُنشر المنفذ 8889 إلى المضيف مطلقاً، لأن Prometheus يصل إلى الجامع عبر شبكة Compose باستخدام اسم الخدمة:

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

يجب أن ينتهي سجل الجامع بـ Everything is ready. Begin running and processing data.. يعني توقف السجل عند خطأ في الإعداد أن ملف YAML لم تتم معالجته بنجاح، وأن الحاوية ستُعاد تهيئتها في حلقة.

وجّه Claude Code إليه الآن. على كل جهاز يشغّل Claude Code، أضف ما يلي إلى ~/.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"
  }
}

ابدأ جلسة، وأرسل مطالبة واحدة، وانتظر فترة التصدير (10 ثوانٍ هنا، و60 ثانية افتراضياً)، ثم اطلب من Prometheus عرض ما تعلّمه:

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

يجب أن تحصل على عدة أسماء تبدأ بـ claude_code_. يعيد المصدّر كتابة النقاط إلى شرطات سفلية ويضيف الوحدة، لذلك تعتمد السلاسل الدقيقة على إصدار الجامع لديك. تعني النتيجة الفارغة عدم وصول أي شيء. تحقق من توافق البروتوكول والمنفذ، لأن http/protobuf يستخدم المنفذ 4318، بينما grpc يستخدم المنفذ 4317، ويؤدي عدم التطابق إلى فشل صامت. شغّل claude --debug، وسيعرض سجل التصحيح أخطاء تصدير OTel.

بالنسبة إلى جهاز واحد ومن دون خادم، تخطَّ كل ما سبق. عيّن OTEL_METRICS_EXPORTER=prometheus، وسيعرض Claude Code نقطة نهاية لجمع المقاييس على http://localhost:9464/metrics نفسه. عندما يكون prometheus هو المصدّر الوحيد المدرج، يحذف Claude Code وحدات USD وtokens وs من أسماء المقاييس، لكي يظل الجمع متوافقاً مع تنسيق نص Prometheus.

يرتبط هذا التصميم بقرار متعلق بالخصوصية. افتراضياً، تغادر الجهازَ العداداتُ فقط، ولا يغادره نص المطالبة ولا ناتج الأدوات. يغيّر OTEL_LOG_USER_PROMPTS=1 وOTEL_LOG_TOOL_CONTENT=1 ذلك، وعندها سيحتوي صندوق المقاييس لديك على الشيفرة المصدرية وأي محتوى آخر كان موجوداً في السياق. فعّل هذين الخيارين عن قصد، واقرأ أولاً إبقاء الأسرار خارج سياق الوكيل.

تتبّع الإنفاق في عمليات التشغيل النصية وعمليات CI

تُفاجئ عمليات التشغيل غير التفاعلية المستخدمين، لأن أحداً لا يراقب الشاشة. يعرض claude -p مع --output-format json تكلفة عملية التشغيل في حمولتها الناتجة:

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

تتضمن الحمولة total_cost_usd بالإضافة إلى تفصيل حسب كل نموذج، ولذلك يمكن لوظيفة CI تسجيل إنفاقها من دون استخدام لوحة معلومات. ألحِق القيمة بملف، أو أرسلها كمقياس إلى جامع المقاييس المذكور أعلاه. هذا أبسط أسلوب مفيد لتتبّع الإنفاق، ولا يتطلب سوى استدعاء واحد من jq لكل عملية تشغيل.

أنماط الفشل وما ستراه

التقرير فارغ. تعني طباعة npx ccusage@latest daily بلا صفوف أنّه لا يقرأ من المكان الذي يكتب فيه Claude Code. ينقل CLAUDE_CONFIG_DIR هذا الموقع، ويجب إبلاغ المحلل به. إذا كانت الصفوف موجودة لكنها تتوقف عند نحو شهر مضى، فهذا يعني أن cleanupPeriodDays يعمل كما هو مصمم: تُحذف النصوص المنقولة بعد 30 يوماً افتراضياً.

يعرض جهازان إجماليين مختلفين. هذا متوقع وليس خطأً. يقرأ كل من /usage وأي محلل للسجلات سجل الجلسات المحلي فقط، لذلك لا يظهر الاستخدام من جهاز آخر أو من claude.ai في أيٍّ منهما.

لا يطابق الإجمالي المحلي قيمة الفاتورة. تُحسب الأرقام المحلية من أعداد الرموز وفق أسعار القائمة القياسية. ولا تراعي هذه الأرقام الأسعار الترويجية أو الخصم المتفق عليه تعاقدياً. وفي الاشتراك، لا تُحاسَب الرموز فردياً أصلاً. تُعد صفحة استخدام Console المرجع المعتمد لفوترة API.

ارتفعت التكلفة رغم أنك نفذت العمل نفسه. افحص أعمدة التخزين المؤقت أولاً. تعيد الجلسة الطويلة إرسال سجلها الكامل في كل دورة. ويُسعَّر ذلك وفق معدل التخزين المؤقت ما دام التخزين المؤقت متاحاً، وبمعدل الإدخال الكامل بعد انتهاء صلاحيته. لذلك تؤدي فترة توقف طويلة واحدة إلى معالجة المحادثة كاملة من جديد. يظهر ذلك كرقم إدخال كبير بجوار رقم إخراج صغير، وتوضح أسعار رموز الإدخال مقابل رموز الإخراج سبب تحرك الرقمين بصورة مستقلة.

يبدو اليوم الذي يحتوي على وكلاء فرعيين غير منطقي. يشغّل كل وكيل فرعي نافذة سياق خاصة به، لذلك يتناسب استخدام الرموز مع عدد الوكلاء الذين عملوا ومدة عمل كل منهم. تفصل بيانات OTel بينهم فقط، من خلال السمة query_source في claude_code.token.usage. أما محلل السجلات فسيعرض الإجمالي ويتركك تحاول معرفة التفاصيل.

FAQ

هل يعرض ccusage ما أدفعه فعلياً ضمن خطة Max؟

لا. في الاشتراك، لا تُحاسَب مقابل كل token، لذلك يحسب محلل السجلات تكلفة tokens وفق أسعار API القياسية المعلنة، ويعرض ما كانت ستكلفه العملية نفسها عبر API. وهذا مقياس نسبي جيد لمدى كثافة يوم معين، كما يفيد في مقارنة المشاريع أو النماذج بعضها ببعض. لمعرفة المبلغ المستحق عليك، تعرض صفحة استخدام Console فواتير API، بينما تعرض صفحة فوترة الخطة تفاصيل فوترة الاشتراك.

أين يخزّن Claude Code ملفات الجلسات التي تقرؤها هذه الأدوات؟

في ~/.claude/projects/<project>/<session-id>.jsonl، حيث يمثّل <project> مسار دليل العمل بعد استبدال الأحرف غير الأبجدية الرقمية بـ -. كل سطر هو كائن JSON لرسالة واحدة أو استخدام أداة أو إدخال بيانات وصفية. ينقل CLAUDE_CONFIG_DIR الدليل بأكمله، ويتحكم cleanupPeriodDays في settings.json في مدة الاحتفاظ البالغة 30 يوماً. توثّق Anthropic تنسيق الإدخالات على أنه داخلي وقابل للتغيير بين الإصدارات، لذلك حلّلها باستخدام أداة تتم صيانتها بدلاً من استخدام script خاص بك.

هل يمكنني إرسال بيانات القياس عن بُعد من Claude Code إلى Langfuse؟

ليس مباشرة. تقبل نقطة نهاية Langfuse الخاصة بـ OTLP آثار التتبع، بينما يصدّر Claude Code المقاييس وأحداث السجل بدلاً من المقاطع، لذلك لا توجد وجهة تستقبل هذه البيانات. أرسل مقاييس Claude Code إلى مجمّع OpenTelemetry وخزّنها في Prometheus. استخدم Langfuse للوكلاء الذين تبنيهم بنفسك على API، حيث يصدر كودك الخاص مقاطع تحمل prompt والنموذج والتكلفة.

لماذا لا تتطابق الأرقام المحلية مع صفحة استخدام Console؟

لأن طريقة حسابها مختلفة. يجمع /usage ومحللو السجلات أعداد tokens من ملفات الجلسات على الجهاز الذي تستخدمه، ثم يحسبون تكلفتها وفق الأسعار القياسية المعلنة. أما Console فيعرض المبلغ الذي فُرض فعلياً على مؤسستك، عبر جميع الأجهزة وجميع المفاتيح، بعد تطبيق أي خصم. عدم التطابق أمر طبيعي. وعادةً ما يعني الفرق الكبير جداً وجود جهاز ثانٍ، أو مشغّل CI، أو عضو آخر في الفريق يستخدم الحساب نفسه للفوترة.

كيف أتتبّع تكلفة تشغيل claude -p في CI؟

شغّله باستخدام --output-format json، واقرأ total_cost_usd من النتيجة، مثلاً باستخدام claude -p "..." --output-format json | jq '.total_cost_usd'. وتتضمن الحمولة نفسها تفصيلاً حسب النموذج ومعرّف الجلسة. سجّل هذه القيمة لكل job، وستحصل على إنفاق كل pipeline من دون agent أو dashboard أو خدمة إضافية.