DEV Community

Cover image for كيفية تقليل تكاليف رموز الوكيل من سطر الأوامر (دليل 2026)
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية تقليل تكاليف رموز الوكيل من سطر الأوامر (دليل 2026)

#agents #ai #cli #productivity

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

جرّب Apidog اليوم

باختصار

لتقليل تكلفة توكنات وكلاء البرمجة:

  • قلّص السياق قبل إرساله إلى النموذج.
  • حدّد الملفات والدلائل التي يعمل عليها الوكيل.
  • اجعل ملفات الذاكرة مثل CLAUDE.md قصيرة ومستقرة.
  • استخدم /compact أو /clear بين المهام.
  • فعّل prompt caching للبادئات المستقرة.
  • وجّه المهام البسيطة إلى نموذج أرخص.
  • قلّل إخراج الأدوات مثل الاختبارات وnpm install.
  • قِس التكلفة لكل تشغيل بدل الاعتماد على الفاتورة الشهرية فقط.

مقدمة

تظهر المشكلة غالبًا بطريقتين:

  1. تصل إلى حد أسبوعي أو حد جلسة في منتصف العمل.
  2. تصل فاتورة API ويسأل الفريق لماذا أصبح “مساعد الذكاء الاصطناعي” بندًا مكلفًا.

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

إعادة هيكلة تحتاج فعليًا إلى 2,000 توكن من الكود لا يجب أن تستخدم 180,000 توكن من السياق. الفرق بين الرقمين هو مساحة التوفير.

في هذا الدليل سنحوّل تقليل التوكنات إلى خطوات عملية:

  • تنظيف السياق وملفات الذاكرة.
  • استخدام prompt caching.
  • توجيه النماذج حسب نوع المهمة.
  • تقليل إخراج الأدوات والاسترجاع.
  • قياس التكلفة لكل تشغيل.

الأمثلة تفترض Claude Code وCodex، لكن الفكرة تنطبق على أي وكيل CLI يتصل بواجهة API تُحاسب بالتوكنات.

💡 إذا كان وكلاؤك يتعاملون مع APIs، فإن تصميمها ومحاكاتها واختبارها في Apidog قبل توجيه الوكيل إليها يقلل التجربة والخطأ المكلفة. يعمل الوكيل ضد عقد API واضح ومستقر بدل نقطة نهاية حية تفاجئه بأخطاء متغيرة.

إلى أين تذهب التوكنات عند تشغيل وكيل CLI؟

كل دور في جلسة الوكيل يرسل حمولة إدخال إلى النموذج ويحصل على حمولة إخراج. أنت تدفع مقابل الاثنين.

عادةً تكون توكنات الإخراج أغلى من الإدخال، لكن الإدخال هو الذي يتضخم بسرعة.

حمولة الإدخال تتكوّن غالبًا من:

  • موجه النظام وتعريفات الأدوات

    تعليمات الوكيل ومخططات JSON الخاصة بالأدوات. قد تكون من 5,000 إلى 15,000 توكن وتُعاد في كل دور.

  • ملفات الذاكرة والمشروع

    مثل CLAUDE.md أو تعليمات المشروع الدائمة. تُحمّل حتى عندما لا تكون مرتبطة بالمهمة.

  • سجل المحادثة

    كل رسالة مستخدم، رد نموذج، استدعاء أداة، ونتيجة أداة يعاد إرسالها. هذا عادةً أكبر مصدر للهدر في الجلسات الطويلة.

  • محتوى الملفات المقروءة

    قراءة ملف من 1,200 سطر قد تعني 12,000 إلى 18,000 توكن.

  • إخراج الأدوات

    سجلات الاختبارات، npm install، git diff، stack traces، وملفات القفل.

النقطة الأهم: سجل المحادثة يُعاد تشغيله في كل دور. جلسة من 30 دورًا لا تكلف 30 مرة فقط، بل تكلف مجموع بادئة تكبر مع الوقت. لذلك الجلسات الطويلة غير المضغوطة هي من أغلى أنماط الاستخدام.

لمزيد من التفاصيل حول حدود الجلسات وحساب التوكنات، راجع: كيفية إعادة تعيين نافذة توكنات كلود كود.

1. نظافة السياق وملفات الذاكرة

أرخص توكن هو التوكن الذي لا ترسله أصلًا.

حدّد نطاق العمل قبل تشغيل الوكيل

لا تبدأ من جذر المستودع بسؤال عام مثل:

claude "أعد هيكلة منطق الفوترة"
Enter fullscreen mode Exit fullscreen mode

هذا يدفع الوكيل للبحث في المستودع كاملًا.

اكتب مهمة محددة:

claude "أعد هيكلة منطق إعادة المحاولة ليستخدم التراجع الأسي.
اعمل فقط على:
- src/payments/retry.ts
- src/payments/retry.test.ts"
Enter fullscreen mode Exit fullscreen mode

إذا كنت لا تعرف الملف بدقة، حدّد الدليل بدل الجذر:

claude "ابحث داخل src/payments فقط عن منطق إعادة المحاولة، ثم اقترح تعديلًا محدودًا"
Enter fullscreen mode Exit fullscreen mode

اجعل CLAUDE.md قصيرًا

ملف الذاكرة مثل CLAUDE.md يُحمّل في كل دور. إذا تحول إلى wiki داخلية، ستدفع ثمنه مرارًا.

افحص حجمه تقريبيًا:

wc -c CLAUDE.md | awk '{print "≈", int($1/4), "توكن لكل دور"}'
Enter fullscreen mode Exit fullscreen mode

اجعل الملف يحتوي فقط على:

  • أوامر البناء والاختبار الأساسية.
  • قواعد الكود الصارمة.
  • بنية المشروع المختصرة.
  • روابط أو مسارات للوثائق الطويلة بدل نسخها داخله.

مثال جيد:

# تعليمات الوكيل

## أوامر
- npm test --silent
- npm run lint

## قواعد
- لا تعدّل ملفات dist/
- لا تغيّر API عام بدون تحديث الاختبارات
- استخدم TypeScript strict types

## وثائق إضافية
- API contracts: docs/api/
- Payment flow: docs/payments.md
Enter fullscreen mode Exit fullscreen mode

اضغط أو امسح الجلسات الطويلة

عندما تنتهي مهمة وتبدأ أخرى، لا تكمل في نفس السياق.

في Claude Code:

/compact
Enter fullscreen mode Exit fullscreen mode

يستبدل السجل الطويل بملخص قصير.

أو:

/clear
Enter fullscreen mode Exit fullscreen mode

يبدأ جلسة جديدة بدون حمل السياق القديم.

قاعدة عملية:

  • مهمة واحدة = جلسة واحدة.
  • بعد الانتهاء: /compact إذا ستكمل على نفس الهدف.
  • استخدم /clear إذا ستنتقل إلى هدف مختلف.

راجع أيضًا: سير عمل كلود كود.

استخدم ملف تجاهل

امنع الوكيل من قراءة ما لا يحتاجه:

node_modules/
dist/
build/
coverage/
.next/
.cache/
*.lock
Enter fullscreen mode Exit fullscreen mode

إذا كان وكيلك يدعم ملف تجاهل مخصص، أضف أيضًا:

docs/generated/
tmp/
vendor/
Enter fullscreen mode Exit fullscreen mode

الهدف: لا تجعل الوكيل يرى ملفات ضخمة لن يعدّلها.

2. Prompt caching: لا تدفع السعر الكامل لنفس البادئة

Prompt caching يسمح للمزود بتخزين بادئة ثابتة من الطلب، مثل:

  • موجه النظام.
  • تعريفات الأدوات.
  • اتفاقيات المشروع.
  • التعليمات المستقرة.

ثم تُقرأ هذه البادئة لاحقًا بخصم كبير بدل إعادة معالجتها بالكامل.

وفقًا لوثائق Anthropic، قراءة cache قد تكلف تقريبًا 10% من تكلفة الإدخال الأساسي، بينما كتابة cache تكلف أكثر قليلًا من الإدخال العادي. لذلك يصبح مفيدًا بسرعة عندما تعيد استخدام نفس البادئة.

القاعدة

ضع المحتوى المستقر أولًا، والمتغير آخرًا.

الترتيب العام:

tools → system → messages
Enter fullscreen mode Exit fullscreen mode

لا تضع طابعًا زمنيًا أو بيانات متغيرة قبل نقطة التخزين المؤقت.

مثال Python 

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": SYSTEM_PROMPT + REPO_CONVENTIONS,
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {
            "role": "user",
            "content": user_task,
        }
    ],
)

u = response.usage

print("cache write:", u.cache_creation_input_tokens)
print("cache read :", u.cache_read_input_tokens)
print("fresh input:", u.input_tokens)
Enter fullscreen mode Exit fullscreen mode

تحقق من أن cache يعمل

إذا كان cache_read_input_tokens يساوي صفرًا دائمًا، فغالبًا لديك أحد هذه الأخطاء:

  • تغيّر البادئة في كل طلب.
  • أضفت timestamp داخل موجه النظام.
  • وضعت محتوى الملف المتغير قبل نقطة cache.
  • البادئة أصغر من الحد الأدنى القابل للتخزين.

اجعل موجه النظام واتفاقيات المشروع ثابتة byte-for-byte قدر الإمكان.

للاستفادة من التوجيه مع Codex، راجع: تشغيل GPT-5.5 مجانًا عبر Codex.

3. توجيه النموذج: استخدم نموذجًا رخيصًا للمهام الرخيصة

ليست كل مهمة تحتاج النموذج الأقوى.

مهام غالبًا يمكن تنفيذها بنموذج أرخص:

  • كتابة commit message.
  • تلخيص git diff.
  • إنشاء changelog.
  • شرح خطأ lint.
  • إعادة تسمية بسيطة.
  • كتابة اختبار نمطي.

مثال:

claude --model haiku "اكتب رسالة commit بنمط conventional commit للتغييرات المرحلية"

claude --model sonnet "أعد تصميم طبقة التخزين المؤقت لخدمة المدفوعات"
Enter fullscreen mode Exit fullscreen mode

اجعل الافتراضي رخيصًا، وصعّد عند الحاجة:

alias claude-cheap='claude --model haiku'
alias claude-strong='claude --model sonnet'
Enter fullscreen mode Exit fullscreen mode

ثم استخدم:

claude-cheap "لخص هذا diff في 5 نقاط"
claude-strong "حلل سبب race condition في طبقة الدفع"
Enter fullscreen mode Exit fullscreen mode

استخدم وكلاء فرعيين بسياق صغير

إذا كان نظامك يدعم sub-agents، اجعل الوكيل الفرعي يعمل على مهمة ضيقة بنموذج رخيص، ثم يعيد ملخصًا قصيرًا للوكيل الرئيسي.

بدلًا من أن يرى النموذج المكلف 30,000 توكن من البحث، يرى 700 توكن من الخلاصة.

مثال نمط عمل:

الوكيل الرئيسي:
- يحدد السؤال.
- يطلب من وكيل فرعي رخيص البحث في src/payments فقط.
- يستقبل ملخصًا قصيرًا.
- يستخدم النموذج الأقوى لاتخاذ القرار النهائي.
Enter fullscreen mode Exit fullscreen mode

راجع: أمر الهدف عبر وكلاء كوديكس وكلود كود المستقلين.

إذا كنت تعمل ضمن حدود أسبوعية، فهذا لا يوفر المال فقط، بل يطيل عمر الحصة. راجع أيضًا: زيادة الحد الأسبوعي لكلود كود الأخيرة.

4. قلّل إخراج الأدوات والاسترجاع

كل سطر تطبعه أداة يمكن أن يدخل السياق، ثم يُعاد في الأدوار اللاحقة.

اجعل الأوامر صامتة

بدل:

npm test
Enter fullscreen mode Exit fullscreen mode

استخدم:

npm test --silent -- --reporter=dot
Enter fullscreen mode Exit fullscreen mode

بدل:

npm install
Enter fullscreen mode Exit fullscreen mode

استخدم:

npm install --silent --no-audit --no-fund
Enter fullscreen mode Exit fullscreen mode

فلتر المخرجات قبل أن يراها الوكيل 

pytest -q 2>&1 | tail -n 30
Enter fullscreen mode Exit fullscreen mode 
git diff --stat
Enter fullscreen mode Exit fullscreen mode 
npm test 2>&1 | grep -E "(FAIL|✗|Error)" | head -n 20
Enter fullscreen mode Exit fullscreen mode

بدل إرجاع سجل اختبار كامل، أعد آخر 30 سطرًا فقط أو الأسطر التي تحتوي على الخطأ.

استخدم قراءة مستهدفة بدل قراءة ملف كامل

اطلب من الوكيل صراحة:

ابحث عن الدالة التي تتعامل مع retry.
اقرأ فقط 80 سطرًا حولها.
لا تقرأ الملف كاملًا إلا إذا لم يكفِ ذلك.
Enter fullscreen mode Exit fullscreen mode

أو استخدم أنت أدوات CLI:

grep -n "function retry" src/payments/retry.ts
sed -n '40,130p' src/payments/retry.ts
Enter fullscreen mode Exit fullscreen mode

فرق التكلفة قد يكون كبيرًا: قراءة 100 سطر بدل 1,500 سطر.

قيّد RAG والاسترجاع

إذا كان الوكيل يسترجع من docs أو code search، لا تسمح له بجلب عشرات القطع الكبيرة.

إعداد عملي:

max_chunks: 8
chunk_size: 300 tokens
Enter fullscreen mode Exit fullscreen mode

أفضل من:

max_chunks: 50
chunk_size: 800 tokens
Enter fullscreen mode Exit fullscreen mode

أنت تدفع مقابل كل قطعة مسترجعة حتى لو لم يستخدمها النموذج.

5. قِس تكلفة التشغيل

لا تعتمد على الانطباع. سجّل التكلفة لكل نوع مهمة.

إذا كنت تستدعي API مباشرة، استخدم كائن usage:

u = response.usage

INPUT_RATE  = 3.00 / 1_000_000
OUTPUT_RATE = 15.00 / 1_000_000
CACHE_READ  = 0.30 / 1_000_000
CACHE_WRITE = 3.75 / 1_000_000

cost = (
    u.input_tokens * INPUT_RATE +
    u.output_tokens * OUTPUT_RATE +
    u.cache_read_input_tokens * CACHE_READ +
    u.cache_creation_input_tokens * CACHE_WRITE
)

print(
    f"تكلفة التشغيل ≈ ${cost:.4f} "
    f"(in={u.input_tokens} out={u.output_tokens} "
    f"cache_read={u.cache_read_input_tokens})"
)
Enter fullscreen mode Exit fullscreen mode

الأسعار هنا توضيحية. استخدم أسعار النموذج الحالية من المزود.

إذا كنت تستخدم CLI فقط:

claude /cost
Enter fullscreen mode Exit fullscreen mode

أو افصل مفاتيح API حسب المشروع:

API key لكل وكيل أو مشروع
→ لوحة تحكم المزود تعرض الإنفاق بشكل قابل للتتبع
Enter fullscreen mode Exit fullscreen mode

أو غلّف تشغيل الوكيل بسكربت يسجل المهمة:

#!/usr/bin/env bash

TASK="$1"
START=$(date -Iseconds)

claude "$TASK"

END=$(date -Iseconds)

echo "$START,$END,$TASK" >> agent-runs.csv
Enter fullscreen mode Exit fullscreen mode

ثم أضف التكلفة المبلغ عنها يدويًا أو من API لاحقًا.

قِس قبل وبعد

اختر مهامًا تمثيلية:

  • إعادة هيكلة يومية.
  • مراجعة PR.
  • توليد اختبار.
  • تلخيص diff.

وسجّل:

task,model,input_tokens,output_tokens,cache_read,cost
Enter fullscreen mode Exit fullscreen mode

بعد تطبيق أي تحسين، يجب أن ترى الرقم يتحرك. إذا لم يتحرك، فالتحسين لا يعالج مصدر الهدر الحقيقي.

مقارنة التكتيكات

التكتيك الوفورات النموذجية الجهد
تحديد نطاق الملفات والدلائل 30–60% من الإدخال لكل تشغيل منخفض
تقصير ملف الذاكرة 5–15% لكل دور منخفض
استخدام /compact أو /clear 40–80% في الجلسات الطويلة منخفض
prompt caching للبادئة المستقرة ~90% على الجزء المخزن متوسط
توجيه المهام البسيطة إلى نموذج أرخص 50–80% على المهام الموجهة متوسط
إخراج أدوات هادئ ومفلتر 20–50% في التشغيلات المعتمدة على الأدوات منخفض
قراءة مستهدفة بدل ملفات كاملة 70–95% في الملفات الكبيرة منخفض
تقليل حجم الاسترجاع/RAG 30–60% في وكلاء البحث متوسط
قياس التكلفة لكل تشغيل لا يوفر مباشرة، لكنه يكشف الهدر منخفض

الأرقام تقريبية وتعتمد على شكل استخدامك، لكنها تساعدك على ترتيب الأولويات.

قائمة تنفيذ سريعة

ابدأ بهذه الخطوات اليوم:

# 1. افحص حجم ملف الذاكرة
wc -c CLAUDE.md | awk '{print "≈", int($1/4), "توكن لكل دور"}'

# 2. استخدم اختبارات هادئة
npm test --silent -- --reporter=dot

# 3. قلل diff
git diff --stat

# 4. امسح الجلسة عند تغيير المهمة
/clear

# 5. اضغط الجلسة الطويلة
/compact
Enter fullscreen mode Exit fullscreen mode

ثم طبّق على مستوى الفريق:

  • راجع CLAUDE.md مرة أسبوعيًا.
  • أضف ملفات التجاهل.
  • اجعل النموذج الأرخص هو الافتراضي للمهام الميكانيكية.
  • فعّل prompt caching إن كنت تتحكم في استدعاءات API.
  • سجّل تكلفة المهام المتكررة.

الخاتمة

تكلفة توكنات وكلاء البرمجة ليست مشكلة حتمية. معظم الهدر يأتي من سياق زائد، جلسات طويلة، مخرجات أدوات صاخبة، ونموذج أقوى من المطلوب.

ابدأ بالأشياء منخفضة الجهد: تحديد النطاق، إخراج هادئ، ملف ذاكرة صغير، و/compact بين المهام. بعد ذلك أضف prompt caching وتوجيه النماذج. النتيجة عادةً تكون فاتورة أقل بدون التضحية بجودة العمل.

Top comments (0)