مصرف توکن و هزینه‌ها

OpenClaw توکن‌ها را ردیابی می‌کند، نه نویسه‌ها را. توکن‌ها وابسته به مدل هستند، اما بیشتر مدل‌های سبک OpenAI به‌طور میانگین برای متن انگلیسی حدود ۴ نویسه به‌ازای هر توکن دارند.

# پرامپت سیستمی چگونه ساخته می‌شود

OpenClaw در هر اجرا پرامپت سیستمی خودش را می‌سازد. این پرامپت شامل موارد زیر است:

• فهرست ابزارها + توضیح‌های کوتاه
• فهرست Skills (فقط فراداده؛ دستورالعمل‌ها هنگام نیاز با read بارگذاری می‌شوند). بلوک فشرده Skills با skills.limits.maxSkillsPromptChars محدود می‌شود، و امکان بازنویسی اختیاری برای هر عامل در agents.list[].skillsLimits.maxSkillsPromptChars وجود دارد.
• دستورالعمل‌های خودبه‌روزرسانی
• فضای کاری + فایل‌های راه‌اندازی (AGENTS.md، SOUL.md، TOOLS.md، IDENTITY.md، USER.md، HEARTBEAT.md، BOOTSTRAP.md هنگام تازه بودن، به‌علاوه MEMORY.md در صورت وجود). ریشه‌ی حروف‌کوچک memory.md تزریق نمی‌شود؛ این ورودی ترمیم قدیمی برای openclaw doctor --fix است، وقتی همراه با MEMORY.md باشد. فایل‌های بزرگ با agents.defaults.bootstrapMaxChars کوتاه می‌شوند (پیش‌فرض: 12000)، و کل تزریق راه‌اندازی با agents.defaults.bootstrapTotalMaxChars محدود می‌شود (پیش‌فرض: 60000). فایل‌های روزانه‌ی memory/*.md بخشی از پرامپت راه‌اندازی معمول نیستند؛ در نوبت‌های عادی همچنان فقط هنگام نیاز از طریق ابزارهای حافظه در دسترس می‌مانند، اما اجراهای بازنشانی/شروع مدل می‌توانند یک بلوک یک‌باره‌ی زمینه‌ی شروع را با حافظه‌ی روزانه‌ی اخیر برای همان نوبت اول پیشوند کنند. دستورهای گفت‌وگوی خام /new و /reset بدون فراخوانی مدل تأیید می‌شوند. پیش‌درآمد شروع با agents.defaults.startupContext کنترل می‌شود.
• زمان (UTC + منطقه زمانی کاربر)
• برچسب‌های پاسخ + رفتار Heartbeat
• فراداده‌ی زمان اجرا (میزبان/سیستم‌عامل/مدل/تفکر)

جزئیات کامل را در پرامپت سیستمی ببینید.

# چه چیزهایی در پنجره‌ی زمینه حساب می‌شوند

هر چیزی که مدل دریافت می‌کند در محدودیت زمینه حساب می‌شود:

• پرامپت سیستمی (همه‌ی بخش‌های فهرست‌شده در بالا)
• تاریخچه‌ی گفتگو (پیام‌های کاربر + دستیار)
• فراخوانی‌های ابزار و نتیجه‌های ابزار
• پیوست‌ها/رونوشت‌ها (تصویر، صوت، فایل)
• خلاصه‌های Compaction و مصنوعات هرس
• پوشش‌های ارائه‌دهنده یا سرآیندهای ایمنی (قابل مشاهده نیستند، اما همچنان حساب می‌شوند)

برخی سطح‌های سنگین در زمان اجرا سقف‌های صریح خودشان را دارند:

• agents.defaults.contextLimits.memoryGetMaxChars
• agents.defaults.contextLimits.memoryGetDefaultLines
• agents.defaults.contextLimits.toolResultMaxChars
• agents.defaults.contextLimits.postCompactionMaxChars

بازنویسی‌های مخصوص هر عامل زیر agents.list[].contextLimits قرار دارند. این تنظیم‌ها برای گزیده‌های محدود زمان اجرا و بلوک‌های تزریق‌شده‌ی متعلق به زمان اجرا هستند. آن‌ها از محدودیت‌های راه‌اندازی، محدودیت‌های زمینه‌ی شروع و محدودیت‌های پرامپت Skills جدا هستند.

برای تصویرها، OpenClaw پیش از فراخوانی‌های ارائه‌دهنده، payloadهای تصویر رونوشت/ابزار را کوچک‌مقیاس می‌کند. برای تنظیم این رفتار از agents.defaults.imageMaxDimensionPx استفاده کنید (پیش‌فرض: 1200):

• مقادیر کمتر معمولاً مصرف توکن‌های بینایی و اندازه‌ی payload را کاهش می‌دهند.
• مقادیر بالاتر جزئیات بصری بیشتری را برای OCR/اسکرین‌شات‌های سنگین UI حفظ می‌کنند.

برای یک تفکیک عملی (به‌ازای هر فایل تزریق‌شده، ابزارها، Skills و اندازه‌ی پرامپت سیستمی)، از /context list یا /context detail استفاده کنید. زمینه را ببینید.

# چگونه مصرف فعلی توکن را ببینید

در گفتگو از این‌ها استفاده کنید:

• /status → کارت وضعیت سرشار از ایموجی با مدل نشست، مصرف زمینه، توکن‌های ورودی/خروجی آخرین پاسخ، و هزینه‌ی تخمینی (فقط کلید API).
• /usage off|tokens|full → یک پاورقی مصرف به‌ازای هر پاسخ به هر پاسخ اضافه می‌کند.
  • برای هر نشست پایدار می‌ماند (به‌صورت responseUsage ذخیره می‌شود).
  • احراز هویت OAuth هزینه را پنهان می‌کند (فقط توکن‌ها).
• /usage cost → خلاصه‌ی هزینه‌ی محلی را از لاگ‌های نشست OpenClaw نشان می‌دهد.

سطح‌های دیگر:

• TUI/Web TUI: /status + /usage پشتیبانی می‌شوند.
• CLI: openclaw status --usage و openclaw channels list پنجره‌های سهمیه‌ی نرمال‌شده‌ی ارائه‌دهنده را نشان می‌دهند (X% left، نه هزینه‌های به‌ازای هر پاسخ). ارائه‌دهندگان فعلی پنجره‌ی مصرف: Anthropic، GitHub Copilot، Gemini CLI، OpenAI Codex، MiniMax، Xiaomi و z.ai.

سطح‌های مصرف پیش از نمایش، نام‌های مستعار رایج فیلدهای بومی ارائه‌دهنده را نرمال‌سازی می‌کنند. برای ترافیک Responses خانواده‌ی OpenAI، این شامل هر دو input_tokens / output_tokens و prompt_tokens / completion_tokens است، بنابراین نام‌های فیلد ویژه‌ی انتقال، /status، /usage یا خلاصه‌های نشست را تغییر نمی‌دهند. مصرف JSON در Gemini CLI هم نرمال‌سازی می‌شود: متن پاسخ از response می‌آید، و stats.cached به cacheRead نگاشت می‌شود و وقتی CLI فیلد صریح stats.input را حذف کند، از stats.input_tokens - stats.cached استفاده می‌شود. برای ترافیک بومی Responses خانواده‌ی OpenAI، نام‌های مستعار مصرف WebSocket/SSE نیز به همین روش نرمال‌سازی می‌شوند، و وقتی total_tokens وجود نداشته باشد یا 0 باشد، مجموع‌ها به ورودی + خروجی نرمال‌شده برمی‌گردند. وقتی snapshot نشست فعلی کم‌جزئیات باشد، /status و session_status می‌توانند شمارنده‌های توکن/کش و برچسب مدل فعال زمان اجرا را نیز از تازه‌ترین لاگ مصرف رونوشت بازیابی کنند. مقدارهای زنده‌ی غیرصفر موجود همچنان بر مقدارهای پشتیبان رونوشت اولویت دارند، و مجموع‌های بزرگ‌تر رونوشت با جهت‌گیری پرامپت می‌توانند وقتی مجموع‌های ذخیره‌شده وجود ندارند یا کوچک‌تر هستند، غالب شوند. احراز هویت مصرف برای پنجره‌های سهمیه‌ی ارائه‌دهنده، در صورت وجود از hookهای ویژه‌ی ارائه‌دهنده می‌آید؛ در غیر این صورت OpenClaw به تطبیق اعتبارنامه‌های OAuth/کلید API از پروفایل‌های احراز هویت، env یا پیکربندی برمی‌گردد. ورودی‌های رونوشت دستیار همان شکل مصرف نرمال‌شده را نگه می‌دارند، از جمله usage.cost وقتی مدل فعال قیمت‌گذاری پیکربندی‌شده داشته باشد و ارائه‌دهنده فراداده‌ی مصرف را برگرداند. این به /usage cost و وضعیت نشست مبتنی بر رونوشت یک منبع پایدار می‌دهد، حتی بعد از اینکه وضعیت زنده‌ی زمان اجرا از بین رفته باشد.

OpenClaw حسابداری مصرف ارائه‌دهنده را از snapshot زمینه‌ی فعلی جدا نگه می‌دارد. usage.total ارائه‌دهنده می‌تواند شامل ورودی کش‌شده، خروجی و چندین فراخوانی مدل در حلقه‌ی ابزار باشد، بنابراین برای هزینه و تله‌متری مفید است اما می‌تواند پنجره‌ی زمینه‌ی زنده را بیش‌ازحد نشان دهد. نمایش‌ها و عیب‌یابی‌های زمینه از تازه‌ترین snapshot پرامپت (promptTokens، یا آخرین فراخوانی مدل وقتی snapshot پرامپت در دسترس نیست) برای context.used استفاده می‌کنند.

# تخمین هزینه (وقتی نمایش داده شود)

هزینه‌ها از پیکربندی قیمت‌گذاری مدل شما تخمین زده می‌شوند:

models.providers.<provider>.models[].cost

این‌ها USD به‌ازای ۱ میلیون توکن برای input، output، cacheRead و cacheWrite هستند. اگر قیمت‌گذاری وجود نداشته باشد، OpenClaw فقط توکن‌ها را نشان می‌دهد. توکن‌های OAuth هرگز هزینه‌ی دلاری را نشان نمی‌دهند.

بعد از اینکه sidecarها و کانال‌ها به مسیر آماده‌ی Gateway برسند، OpenClaw یک راه‌اندازی اختیاری قیمت‌گذاری پس‌زمینه را برای ارجاع‌های مدل پیکربندی‌شده‌ای شروع می‌کند که از قبل قیمت‌گذاری محلی ندارند. این راه‌اندازی، کاتالوگ‌های قیمت‌گذاری راه‌دور OpenRouter و LiteLLM را دریافت می‌کند. برای رد کردن این دریافت‌های کاتالوگ در شبکه‌های آفلاین یا محدود، models.pricing.enabled: false را تنظیم کنید؛ ورودی‌های صریح models.providers.*.models[].cost همچنان تخمین‌های هزینه‌ی محلی را هدایت می‌کنند.

# TTL کش و اثر هرس

کش‌کردن پرامپت ارائه‌دهنده فقط درون پنجره‌ی TTL کش اعمال می‌شود. OpenClaw می‌تواند به‌صورت اختیاری هرس TTL کش را اجرا کند: پس از منقضی شدن TTL کش، نشست را هرس می‌کند و سپس پنجره‌ی کش را بازنشانی می‌کند تا درخواست‌های بعدی بتوانند به‌جای کش‌کردن دوباره‌ی کل تاریخچه، از زمینه‌ی تازه کش‌شده دوباره استفاده کنند. این کار وقتی یک نشست پس از TTL بی‌کار می‌ماند، هزینه‌های نوشتن کش را پایین‌تر نگه می‌دارد.

آن را در پیکربندی Gateway تنظیم کنید و جزئیات رفتار را در هرس نشست ببینید.

Heartbeat می‌تواند کش را در فاصله‌های بی‌کاری گرم نگه دارد. اگر TTL کش مدل شما 1h است، تنظیم فاصله‌ی Heartbeat کمی کمتر از آن (مثلاً 55m) می‌تواند از کش‌کردن دوباره‌ی کل پرامپت جلوگیری کند و هزینه‌های نوشتن کش را کاهش دهد.

در تنظیمات چندعاملی، می‌توانید یک پیکربندی مدل مشترک نگه دارید و رفتار کش را برای هر عامل با agents.list[].params.cacheRetention تنظیم کنید.

برای راهنمای کامل تک‌به‌تک تنظیم‌ها، کش پرامپت را ببینید.

برای قیمت‌گذاری API در Anthropic، خواندن‌های کش به‌طور قابل‌توجهی ارزان‌تر از توکن‌های ورودی هستند، در حالی که نوشتن‌های کش با ضریب بالاتری صورت‌حساب می‌شوند. برای تازه‌ترین نرخ‌ها و ضرایب TTL، قیمت‌گذاری کش پرامپت Anthropic را ببینید: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

# مثال: گرم نگه داشتن کش 1h با Heartbeat

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
    heartbeat:
      every: "55m"

# مثال: ترافیک ترکیبی با راهبرد کش برای هر عامل

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long" # default baseline for most agents
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m" # keep long cache warm for deep sessions
    - id: "alerts"
      params:
        cacheRetention: "none" # avoid cache writes for bursty notifications

agents.list[].params روی params مدل انتخاب‌شده ادغام می‌شود، بنابراین می‌توانید فقط cacheRetention را بازنویسی کنید و سایر پیش‌فرض‌های مدل را بدون تغییر به ارث ببرید.

# مثال: فعال‌سازی سرآیند بتای زمینه‌ی 1M در Anthropic

پنجره‌ی زمینه‌ی 1M در Anthropic در حال حاضر پشت دروازه‌ی بتا است. OpenClaw می‌تواند مقدار ضروری anthropic-beta را وقتی context1m را روی مدل‌های پشتیبانی‌شده‌ی Opus یا Sonnet فعال کنید، تزریق کند.

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          context1m: true

این به سرآیند بتای context-1m-2025-08-07 در Anthropic نگاشت می‌شود.

این فقط زمانی اعمال می‌شود که context1m: true روی آن ورودی مدل تنظیم شده باشد.

نیازمندی: اعتبارنامه باید برای مصرف زمینه‌ی بلند واجد شرایط باشد. در غیر این صورت، Anthropic برای آن درخواست با خطای محدودیت نرخ سمت ارائه‌دهنده پاسخ می‌دهد.

اگر Anthropic را با توکن‌های OAuth/اشتراک (sk-ant-oat-*) احراز هویت کنید، OpenClaw سرآیند بتای context-1m-* را رد می‌کند، چون Anthropic در حال حاضر این ترکیب را با HTTP 401 رد می‌کند.

# نکته‌هایی برای کاهش فشار توکن

• برای خلاصه‌کردن نشست‌های طولانی از /compact استفاده کنید.
• خروجی‌های بزرگ ابزار را در گردش‌کارهای خود کوتاه کنید.
• برای نشست‌هایی که اسکرین‌شات زیادی دارند، agents.defaults.imageMaxDimensionPx را کاهش دهید.
• توضیح‌های Skills را کوتاه نگه دارید (فهرست Skill در پرامپت تزریق می‌شود).
• برای کارهای پرحرف و اکتشافی، مدل‌های کوچک‌تر را ترجیح دهید.

برای فرمول دقیق سربار فهرست Skill، Skills را ببینید.

# مرتبط

• مصرف و هزینه‌های API
• کش پرامپت
• ردیابی مصرف