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

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

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

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

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

شرح کامل را در پرامپت سیستمی ببینید.

هنگام مستندسازی اعتبارنامه‌ها یا قطعه‌های احراز هویت، برای جلوگیری از مثبت کاذب اسکنر اسرار در تغییرات صرفاً مستنداتی، از قراردادهای جای‌نگهدار راز استفاده کنید.

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

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

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

سطوح سنگین از نظر زمان اجرا، محدودیت‌های صریح خود را در agents.defaults.contextLimits دارند (بازنویسی‌های هر عامل در agents.list[].contextLimits):

این‌ها گزیده‌های محدودشدهٔ زمان اجرا و بلوک‌های تزریق‌شدهٔ تحت مالکیت زمان اجرا هستند و از محدودیت‌های راه‌اندازی اولیه، محدودیت‌های زمینهٔ راه‌اندازی و محدودیت‌های پرامپت مهارت‌ها جدا هستند.

toolResultMaxChars به‌طور پیش‌فرض تنظیم نشده است، بنابراین OpenClaw سقف نتیجهٔ ابزار زنده را از پنجرهٔ زمینهٔ مؤثر مدل استخراج می‌کند: 16000 نویسه برای کمتر از ۱۰۰ هزار توکن، 32000 نویسه برای ۱۰۰ هزار توکن یا بیشتر و 64000 نویسه برای ۲۰۰ هزار توکن یا بیشتر. حتی زمانی که سقف صریح بزرگ‌تری پیکربندی شده باشد، محافظ سهم زمینهٔ زمان اجرا همچنان نتیجهٔ یک ابزار را به ۳۰٪ پنجرهٔ زمینه محدود می‌کند.

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

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

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

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

در گپ:

• /status -> کارت وضعیت سرشار از ایموجی شامل مدل نشست، مصرف زمینه، توکن‌های ورودی/خروجی آخرین پاسخ و هزینهٔ تخمینی، در صورتی که قیمت‌گذاری محلی برای مدل فعال پیکربندی شده باشد.
• /usage off|tokens|full -> به هر پاسخ یک پانویس مصرفِ مختص همان پاسخ اضافه می‌کند. این تنظیم برای هر نشست ماندگار است (با نام responseUsage ذخیره می‌شود).
  • /usage reset (نام‌های مستعار: inherit، clear، default) بازنویسی نشست را پاک می‌کند تا دوباره پیش‌فرض پیکربندی‌شده را به ارث ببرد.
  • /usage tokens جزئیات توکن/حافظهٔ نهان نوبت را نشان می‌دهد.
  • /usage full جزئیات فشردهٔ مدل/زمینه/هزینه را نشان می‌دهد؛ هزینهٔ تخمینی فقط زمانی نمایش داده می‌شود که OpenClaw فرادادهٔ مصرف و قیمت‌گذاری محلی مدل فعال را داشته باشد. چیدمان‌های سفارشی messages.usageTemplate می‌توانند فیلدهای توکن/حافظهٔ نهان را در بر گیرند.
• /usage cost -> خلاصهٔ هزینهٔ محلی از گزارش‌های نشست OpenClaw.

سایر سطوح:

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

سطوح مصرف، نام‌های مستعار رایج فیلدهای بومی ارائه‌دهنده را پیش از نمایش عادی‌سازی می‌کنند. برای ترافیک Responses خانوادهٔ OpenAI، این شامل هر دو جفت input_tokens/output_tokens و prompt_tokens/completion_tokens است؛ بنابراین نام فیلدهای مختص انتقال، /status، /usage یا خلاصه‌های نشست را تغییر نمی‌دهند. مصرف Gemini CLI نیز عادی‌سازی می‌شود: تجزیه‌گر پیش‌فرض stream-json رویدادهای message دستیار را می‌خواند و stats.cached به cacheRead نگاشت می‌شود؛ همچنین وقتی CLI فیلد صریح stats.input را حذف کند، از stats.input_tokens - stats.cached استفاده می‌شود. بازنویسی‌های قدیمی JSON همچنان متن پاسخ را از response می‌خوانند.

برای ترافیک بومی Responses خانوادهٔ OpenAI، نام‌های مستعار مصرف WebSocket/SSE نیز به همین روش عادی‌سازی می‌شوند و اگر total_tokens وجود نداشته باشد یا 0 باشد، مجموع از ورودی + خروجی عادی‌سازی‌شده محاسبه می‌شود.

وقتی تصویر لحظه‌ای نشست فعلی کم‌اطلاعات باشد، /status و session_status می‌توانند شمارنده‌های توکن/حافظهٔ نهان و برچسب مدل فعال زمان اجرا را از جدیدترین گزارش مصرف رونوشت بازیابی کنند. مقادیر زندهٔ غیرصفر موجود همچنان بر مقادیر جایگزین رونوشت اولویت دارند و وقتی مجموع‌های ذخیره‌شده وجود نداشته باشند یا کوچک‌تر باشند، مجموع‌های بزرگ‌ترِ پرامپت‌محورِ رونوشت می‌توانند اولویت پیدا کنند.

احراز هویت مصرف برای پنجره‌های سهمیهٔ ارائه‌دهنده ابتدا از قلاب‌های مختص ارائه‌دهنده به دست می‌آید؛ اگر ارائه‌دهنده‌ای قلاب نداشته باشد (یا قلاب نتواند توکنی را پیدا کند)، OpenClaw به اعتبارنامه‌های منطبق OAuth/کلید API در پروفایل‌های احراز هویت، متغیرهای محیطی یا پیکربندی بازمی‌گردد.

ورودی‌های رونوشت دستیار همان شکل عادی‌سازی‌شدهٔ مصرف، از جمله usage.cost، را ماندگار می‌کنند؛ مشروط بر اینکه برای مدل فعال قیمت‌گذاری پیکربندی شده باشد و ارائه‌دهنده فرادادهٔ مصرف را بازگرداند. این کار حتی پس از از بین رفتن وضعیت زندهٔ زمان اجرا، منبعی پایدار برای /usage cost و وضعیت نشست مبتنی بر رونوشت فراهم می‌کند.

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

تخمین هزینه (هنگام نمایش)

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

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

این مقادیر برای input، output، cacheRead و cacheWrite، دلار آمریکا به‌ازای هر ۱ میلیون توکن هستند. اگر قیمت‌گذاری وجود نداشته باشد، /usage full هزینه را حذف می‌کند؛ وقتی در هر پاسخ به جزئیات توکن/حافظهٔ نهان نیاز دارید، از /usage tokens یا یک messages.usageTemplate سفارشی استفاده کنید. نمایش هزینه به احراز هویت با کلید API محدود نیست: ارائه‌دهندگان بدون کلید API مانند aws-sdk می‌توانند زمانی هزینهٔ تخمینی را نشان دهند که ورودی مدل پیکربندی‌شدهٔ آن‌ها شامل قیمت‌گذاری محلی باشد و ارائه‌دهنده فرادادهٔ مصرف را بازگرداند.

پس از آنکه پردازه‌های جانبی و کانال‌ها به مسیر آمادهٔ 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

مثال: گرم نگه داشتن حافظهٔ نهان ۱ ساعته با 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 را بازنویسی کنید و سایر پیش‌فرض‌های مدل را بدون تغییر به ارث ببرید.

زمینهٔ ۱ میلیونی Anthropic

OpenClaw اندازهٔ زمینهٔ مدل‌های Claude 4.x با قابلیت دسترسی عمومی، مانند Opus 4.8، Opus 4.7، Opus 4.6 و Sonnet 4.6 را مطابق پنجرهٔ زمینهٔ ۱ میلیونی Anthropic تنظیم می‌کند. برای این مدل‌ها به params.context1m: true نیاز ندارید.

agents:  defaults:    models:      "anthropic/claude-opus-4-6":        alias: opus

پیکربندی‌های قدیمی‌تر می‌توانند context1m: true را حفظ کنند، اما OpenClaw دیگر سرآیند بتای منسوخ‌شدهٔ context-1m-2025-08-07 شرکت Anthropic را برای این تنظیم ارسال نمی‌کند و مدل‌های قدیمی‌تر و پشتیبانی‌نشدهٔ Claude را به ۱ میلیون گسترش نمی‌دهد.

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

اگر برای احراز هویت Anthropic از توکن‌های OAuth/اشتراک (sk-ant-oat-*) استفاده کنید، OpenClaw سرآیندهای بتای Anthropic موردنیاز OAuth را حفظ می‌کند، اما اگر بتای منسوخ‌شدهٔ context-1m-* همچنان در پیکربندی قدیمی‌تر وجود داشته باشد، آن را حذف می‌کند.

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

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

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

مرتبط

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