بک‌اندهای CLI

OpenClaw می‌تواند هنگامی که ارائه‌دهندگان API از دسترس خارج‌اند، با محدودیت نرخ مواجه شده‌اند یا درست عمل نمی‌کنند، یک CLI هوش مصنوعی محلی را به‌عنوان راهکار جایگزین صرفاً متنی اجرا کند. این قابلیت عمداً محافظه‌کارانه طراحی شده است:

• ابزارهای OpenClaw مستقیماً تزریق نمی‌شوند، اما یک بک‌اند دارای bundleMcp: true می‌تواند ابزارهای Gateway را از طریق یک پل MCP لوپ‌بک دریافت کند.
• استریم JSONL برای CLIهایی که از آن پشتیبانی می‌کنند.
• نشست‌ها پشتیبانی می‌شوند، بنابراین نوبت‌های بعدی منسجم باقی می‌مانند.
• اگر CLI مسیرهای تصویر را بپذیرد، تصاویر نیز منتقل می‌شوند.

از آن به‌عنوان یک شبکهٔ ایمنی برای پاسخ‌های متنی «همیشه کار می‌کند» استفاده کنید، نه مسیر اصلی. برای یک محیط اجرایی کامل با کنترل‌های نشست ACP، وظایف پس‌زمینه، اتصال رشته/مکالمه و نشست‌های خارجی کدنویسی پایدار، به‌جای آن از عامل‌های ACP استفاده کنید؛ بک‌اندهای CLI از نوع ACP نیستند.

شروع سریع

Plugin همراه Anthropic یک بک‌اند پیش‌فرض claude-cli ثبت می‌کند؛ بنابراین به‌جز نصب‌بودن Claude Code و ورود به حساب، بدون هیچ پیکربندی دیگری کار می‌کند:

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

وقتی فهرست صریحی از عامل‌ها پیکربندی نشده باشد، main شناسهٔ پیش‌فرض عامل است؛ در غیر این صورت، شناسهٔ عامل خود را جایگزین کنید.

سرویس Gateway باید CLI را در PATH خود داشته باشد. اگر یک استقرار به مسیر اجرایی یا آرگومان‌های غیراستاندارد نیاز دارد، به‌جای قرار دادن سازوکارهای راه‌اندازی در openclaw.json، آن آداپتور را در یک Plugin بک‌اند CLI ثبت کنید.

OpenClaw هنگامی که انتخاب مدل یا یک agentRuntime.id مختص مدل به بک‌اند آن ارجاع دهد، Plugin همراه مالک را به‌طور خودکار بارگذاری می‌کند.

استفاده به‌عنوان راهکار جایگزین

بک‌اند CLI را به فهرست جایگزین‌های خود اضافه کنید تا فقط هنگام شکست مدل‌های اصلی اجرا شود:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-opus-4-6",        fallbacks: ["claude-cli/claude-sonnet-4-6"],      },      models: {        "anthropic/claude-opus-4-6": { alias: "Opus" },        "claude-cli/claude-sonnet-4-6": {},      },    },  },}

وقتی ارائه‌دهندهٔ اصلی با شکست مواجه شود (احراز هویت، محدودیت نرخ یا پایان مهلت)، جایگزین‌های پیکربندی‌شده همچنان واجد شرایط می‌مانند، حتی اگر در agents.defaults.modelPolicy.allow نباشند. فقط زمانی یک مدل بک‌اند CLI را به آن سیاست اضافه کنید که کاربران باید بتوانند آن را مستقیماً از طریق /model، یک بازنویسی نشست یا --model نیز انتخاب کنند. agents.defaults.models فقط مالک نام‌های مستعار، پارامترها و فراداده‌های هر مدل است.

پیکربندی

کاربران از طریق سیاست مدل و محیط اجرا، یک بک‌اند ثبت‌شده را انتخاب می‌کنند. ارجاع مدل را استاندارد نگه دارید و محیط اجرای CLI را برای هر مدل انتخاب کنید:

{  agents: {    defaults: {      model: "anthropic/claude-opus-5",      models: {        "anthropic/claude-opus-5": {          agentRuntime: { id: "claude-cli" },        },      },    },  },}

اعتبارنامه‌ها در پروفایل‌های احراز هویت OpenClaw یا پیکربندی Plugin مالک باقی می‌مانند. فرمان، argv، محیط، تجزیه، نشست، تصویر و سازوکارهای ناظر کد Plugin هستند که با api.registerCliBackend(...) ثبت شده‌اند.

نحوهٔ کار

1. یک بک‌اند را براساس پیشوند ارائه‌دهنده انتخاب می‌کند (claude-cli/...).
2. با استفاده از همان پرامپت OpenClaw و زمینهٔ فضای کاری، یک پرامپت سیستمی می‌سازد.
3. CLI را با یک شناسهٔ نشست اجرا می‌کند (در صورت پشتیبانی) تا تاریخچه سازگار باقی بماند. بک‌اند همراه claude-cli برای هر نشست OpenClaw یک فرایند stdio متعلق به Claude را فعال نگه می‌دارد و نوبت‌های بعدی را از طریق ورودی استاندارد stream-json ارسال می‌کند.
4. خروجی را تجزیه می‌کند (JSON یا متن ساده) و متن نهایی را برمی‌گرداند.
5. شناسه‌های نشست را برای هر بک‌اند ذخیره می‌کند تا نوبت‌های بعدی دوباره از همان نشست CLI استفاده کنند.

پایان مهلت‌ها و کارهای طولانی‌مدت

بک‌اندهای CLI دو محدودیت مستقل دارند:

• agents.defaults.timeoutSeconds کل نوبت عامل را محدود می‌کند. نوبت‌های عادی Gateway پیش‌فرض 48 ساعته را به ارث می‌برند؛ 0 بودجهٔ زمانی نوبت را نامحدود می‌کند. یک بازنویسی ذخیره‌شده مانند 600 جایگزین آن پیش‌فرض می‌شود.
• ناظرِ بدون خروجی CLI، زیرفرایندی را که ساکت باقی بماند متوقف می‌کند. هر Plugin بک‌اند مالک پروفایل‌های جداگانهٔ تازه/ازسرگیری است و ناظر حتی زمانی که بودجهٔ کلی نوبت نامحدود باشد، فعال باقی می‌ماند.

برای بازگشت به پیش‌فرض 48 ساعته، بازنویسی کوتاه پایان مهلت کلی را حذف کنید یا بودجه‌ای صریح مانند 12 ساعت تنظیم کنید:

# بازگشت به پیش‌فرض 48 ساعته:openclaw config unset agents.defaults.timeoutSeconds # یا انتخاب محدودیت صریح 12 ساعته:openclaw config set agents.defaults.timeoutSeconds 43200

کار پس‌زمینه‌ای که درون یک CLI آغاز می‌شود همچنان بخشی از همان زیرفرایند CLI است. اگر نوبت والد به محدودیت کلی خود برسد، OpenClaw زیرفرایند و وظایف پس‌زمینهٔ داخلی CLI آن را با هم متوقف می‌کند. برای کار طولانی و پایدار، از یک زیرعامل جداشدهٔ OpenClaw یا عامل ACP استفاده کنید؛ زیرعامل‌های جداشده به‌طور پیش‌فرض پایان مهلت اجرا ندارند.

فرمان openclaw agent نیز مهلت درخواست مختص خود را دارد. پیش‌فرض جایگزین 600 ثانیه‌ای آن برای همان فراخوانی فرمان اعمال می‌شود، نه نوبت‌های عادی Gateway؛ openclaw agent را ببینید.

جزئیات Claude CLI

بک‌اند همراه claude-cli ترجیح می‌دهد از تفکیک‌گر بومی مهارت Claude Code استفاده کند. وقتی تصویر لحظه‌ای فعلی مهارت‌ها دست‌کم یک مهارت انتخاب‌شده با مسیر مادی‌سازی‌شده داشته باشد، OpenClaw از طریق --plugin-dir یک Plugin موقت Claude Code ارسال می‌کند و کاتالوگ تکراری مهارت‌های OpenClaw را از پرامپت سیستمی افزوده‌شده حذف می‌کند. بدون مهارت Plugin مادی‌سازی‌شده، OpenClaw کاتالوگ پرامپت را به‌عنوان جایگزین نگه می‌دارد. بازنویسی‌های محیطی/کلید API مهارت همچنان برای اجرای موردنظر روی محیط فرایند فرزند اعمال می‌شوند.

Claude CLI حالت مجوز غیرتعاملی مختص خود را دارد؛ OpenClaw به‌جای افزودن پیکربندی مختص Claude، آن را به سیاست اجرایی موجود نگاشت می‌کند. برای نشست‌های زندهٔ Claude تحت مدیریت OpenClaw، سیاست اجرایی مؤثر مرجع نهایی است: حالت YOLO ‏(tools.exec.mode: "full") معمولاً Claude را با --permission-mode bypassPermissions راه‌اندازی می‌کند، درحالی‌که یک سیاست محدودکننده آن را با --permission-mode default راه‌اندازی می‌کند. Gatewayهایی که با کاربر root اجرا می‌شوند نیز از default استفاده می‌کنند، زیرا Claude Code حالت دورزدن را برای root رد می‌کند. تنظیمات agents.entries.*.tools.exec هر عامل، tools.exec سراسری را برای همان عامل بازنویسی می‌کنند. Plugin ‏Anthropic پرچم‌های مجوز Claude را برای تطبیق با سیاست مؤثر و محدودیت میزبان نرمال‌سازی می‌کند.

تحت یک سیاست محدودکننده، Claude پیش از استفاده از یکی از ابزارهای بومی یا افزونه‌ای خود (ابزارهای Bash، ‏WebFetch یا مرورگر Claude in Chrome خودش) از طریق stdio از OpenClaw اجازه می‌خواهد. وقتی تنظیم مؤثر پرسش اجرایی on-miss یا always باشد، OpenClaw هر درخواست را به‌عنوان تأیید تعاملی به کانال نشست منتقل می‌کند: یک‌بار اجازه بده فقط همان فراخوانی را مجاز می‌کند، همیشه اجازه بده آن نام ابزار را برای باقی نشست زندهٔ Claude مجاز می‌کند (فقط در حافظه و هرگز ذخیره نمی‌شود)، و رد کردن، پایان مهلت یا مسیر تأیید غیرقابل‌دسترسی همگی فراخوانی را رد می‌کنند. سیاست‌هایی که هرگز درخواست تأیید نمی‌کنند رفتار قبلی خود را حفظ می‌کنند: security: "deny" هر درخواست را رد می‌کند، و پرسش off با امنیت کمتر از کامل (حالت اجرایی allowlist) بدون پرسیدن رد می‌شود.

ابزارهای مرورگر Claude و ورود به 1Password

Claude Code می‌تواند از طریق افزونهٔ Claude in Chrome یک مرورگر Chrome را کنترل کند، ازجمله تکمیل خودکار اعتبارنامه با 1Password برای Claude. بک‌اند همراه آن را فعال نمی‌کند؛ یک Plugin بک‌اند CLI ثبت کنید که --chrome را به آرگومان‌های راه‌اندازی یک بک‌اند با گویش claude-stream-json بیفزاید. OpenClaw در اجراهای عادی یک --chrome پیکربندی‌شده را حفظ می‌کند و در اجراهایی با سیاست ابزار محدود، مانند پرسش‌های جانبی، همیشه --no-chrome را تحمیل می‌کند. پنجرهٔ Chrome، افزونه و هر درخواست تأیید 1Password روی میزبان Gateway قرار دارند؛ بنابراین شخصی باید کنار آن دستگاه حضور داشته باشد تا استفاده از اعتبارنامه را تأیید کند.

این بک‌اند همچنین سطوح /think در OpenClaw را به پرچم بومی --effort در Claude Code نگاشت می‌کند: minimal/low -> low، ‏medium -> medium، و high/xhigh/max مستقیماً منتقل می‌شوند. به‌این‌ترتیب، سطوح تلاش پشتیبانی‌شدهٔ Fable 5 برای Claude CLI مبتنی بر اشتراک و مسیرهای کلید API یکسان می‌مانند. adaptive پرچم‌های --effort پیکربندی‌شده را حذف می‌کند و جایگزینی ارائه نمی‌دهد؛ بنابراین Claude Code میزان تلاش مؤثر را از محیط، تنظیمات و پیش‌فرض‌های مدل خودش تعیین می‌کند. برای اینکه /think بر CLI راه‌اندازی‌شده اثر بگذارد، سایر بک‌اندهای CLI باید Plugin مالک خود را وادار کنند یک نگاشت‌کنندهٔ معادل argv تعریف کند.

پیش از آنکه OpenClaw بتواند از claude-cli استفاده کند، خود Claude Code باید روی همان میزبان وارد حساب شده باشد:

claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

در نصب‌های Docker، ‏Claude Code باید درون خانهٔ پایدار کانتینر نصب شده و وارد حساب شده باشد، نه فقط روی میزبان؛ بک‌اند Claude CLI در Docker را ببینید.

سرویس Gateway باید بتواند claude را در PATH پیدا کند. برای یک مسیر غیراستاندارد، یک Plugin بک‌اند پوششی کوچک ثبت کنید.

نشست‌ها

• اگر CLI از نشست‌ها پشتیبانی می‌کند، sessionArgs را با یک جای‌نگهدار {sessionId} تنظیم کنید (برای مثال ["--session-id", "{sessionId}"]).
• اگر CLI از زیرفرمان ازسرگیری با پرچم‌های متفاوت استفاده می‌کند، resumeArgs را تنظیم کنید (هنگام ازسرگیری جایگزین args می‌شود) و در صورت نیاز resumeOutput را برای ازسرگیری‌های غیر JSON تنظیم کنید.
• sessionMode:
  • always: همیشه یک شناسهٔ نشست ارسال می‌کند (اگر شناسه‌ای ذخیره نشده باشد، یک UUID جدید).
  • existing: فقط در صورتی شناسهٔ نشست ارسال می‌کند که قبلاً یکی ذخیره شده باشد.
  • none: هرگز شناسهٔ نشست ارسال نمی‌کند.
• claude-cli به‌طور پیش‌فرض از liveSession: "claude-stdio"، ‏output: "jsonl" و input: "stdin" استفاده می‌کند؛ بنابراین تا زمانی که فرایند زندهٔ Claude فعال است، نوبت‌های بعدی دوباره از آن استفاده می‌کنند، حتی برای پیکربندی‌های سفارشی که فیلدهای انتقال را حذف کرده‌اند. اگر Gateway راه‌اندازی مجدد شود یا فرایند بیکار خارج شود، OpenClaw از شناسهٔ نشست ذخیره‌شدهٔ Claude ازسرگیری می‌کند. پیش از ازسرگیری، شناسه‌های نشست ذخیره‌شده در برابر یک رونوشت پروژهٔ خواندنی اعتبارسنجی می‌شوند؛ نبود رونوشت به‌جای آغاز بی‌سروصدای یک نشست تازه تحت --resume، اتصال را پاک می‌کند (با ثبت گزارش به‌صورت reason=transcript-missing).
• نشست‌های زندهٔ Claude محافظ‌های محدودشدهٔ خروجی JSONL را حفظ می‌کنند: 8 MiB و 20,000 خط خام JSONL در هر نوبت.
• نشست‌های ذخیره‌شدهٔ CLI تداومی تحت مالکیت ارائه‌دهنده هستند. بازنشانی خودکار به‌طور پیش‌فرض غیرفعال است؛ /reset و سیاست‌های صریح روزانه یا بیکاری session.reset همچنان آن‌ها را قطع می‌کنند.
• نشست‌های تازهٔ CLI معمولاً فقط از خلاصهٔ Compaction در OpenClaw به‌همراه دنبالهٔ پس از Compaction دوباره مقداردهی اولیه می‌شوند. برای بازیابی نشست‌های کوتاهی که پیش از Compaction نامعتبر شده‌اند، یک بک‌اند می‌تواند با reseedFromRawTranscriptWhenUncompacted: true این قابلیت را فعال کند. مقداردهی مجدد از رونوشت خام همچنان محدود و منحصر به نامعتبرشدن‌های امن است؛ مانند نبود رونوشت CLI، دنبالهٔ یتیم استفاده از ابزار، تغییرات سیاست پیام/پرامپت سیستمی/cwd/MCP یا تلاش مجدد پس از انقضای نشست؛ تغییر پروفایل احراز هویت یا دورهٔ اعتبارنامه هرگز تاریخچهٔ رونوشت خام را دوباره مقداردهی نمی‌کند.

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

مقدمهٔ جایگزین از نشست‌های claude-cli

هنگامی که یک تلاش claude-cli در agents.defaults.model.fallbacks به یک گزینهٔ غیر CLI منتقل می‌شود، OpenClaw تلاش بعدی را با یک پیش‌درآمد زمینه‌ای آغاز می‌کند که از رونوشت محلی JSONL مربوط به Claude Code (در ~/.claude/projects/، با کلیدی جداگانه برای هر فضای کاری) استخراج شده است. بدون این دادهٔ اولیه، ارائه‌دهندهٔ جایگزین به‌صورت سرد شروع می‌شود، زیرا رونوشت نشست خود OpenClaw برای اجراهای claude-cli خالی است.

• پیش‌درآمد، جدیدترین خلاصهٔ /compact یا نشانگر compact_boundary را ترجیح می‌دهد و سپس جدیدترین نوبت‌های پس از مرز را تا سقف بودجهٔ نویسه اضافه می‌کند. نوبت‌های پیش از مرز حذف می‌شوند، زیرا خلاصه از قبل آن‌ها را بازنمایی می‌کند.
• بلوک‌های ابزار در راهنمای فشردهٔ (tool call: name) و (tool result: …) ادغام می‌شوند تا بودجهٔ پرامپت دقیق باقی بماند؛ خلاصه‌ای که بیش‌ازحد بزرگ باشد کوتاه و با (truncated) برچسب‌گذاری می‌شود.
• جایگزینی‌های همان ارائه‌دهنده از claude-cli به claude-cli به --resume خود Claude متکی هستند و پیش‌درآمد را نادیده می‌گیرند.
• دادهٔ اولیه از اعتبارسنجی موجود مسیر فایل نشست Claude دوباره استفاده می‌کند؛ بنابراین امکان خواندن مسیرهای دلخواه وجود ندارد.

تصاویر

نویسندگان Plugin پشتیبانی از مسیر تصویر را با imageArg اعلام می‌کنند:

imageArg: "--image",imageMode: "repeat"

OpenClaw تصاویر base64 را در فایل‌های موقت می‌نویسد. اگر imageArg تنظیم شده باشد، آن مسیرها به‌عنوان آرگومان‌های CLI ارسال می‌شوند؛ در غیر این صورت، OpenClaw مسیر فایل‌ها را به پرامپت می‌افزاید (تزریق مسیر) که برای CLIهایی که فایل‌های محلی را به‌طور خودکار از مسیرهای ساده بارگذاری می‌کنند، کار می‌کند.

ورودی‌ها و خروجی‌ها

• output: "text" (پیش‌فرض) stdout را پاسخ نهایی در نظر می‌گیرد.
• output: "json" تلاش می‌کند JSON را تجزیه و متن را به‌همراه شناسهٔ نشست استخراج کند.
• output: "jsonl" یک جریان JSONL را تجزیه می‌کند و پیام نهایی عامل را به‌همراه شناسه‌های نشست، در صورت وجود، استخراج می‌کند.
• برای خروجی JSON مربوط به Gemini CLI، هنگامی که usage وجود ندارد یا خالی است، OpenClaw متن پاسخ را از response و میزان مصرف را از stats می‌خواند. سازگارکنندهٔ همراه Gemini CLI از stream-json استفاده می‌کند.

حالت‌های ورودی:

• input: "arg" (پیش‌فرض) پرامپت را به‌عنوان آخرین آرگومان CLI ارسال می‌کند.
• input: "stdin" پرامپت را از طریق stdin ارسال می‌کند.
• اگر پرامپت بسیار طولانی باشد و maxPromptArgChars تنظیم شده باشد، به‌جای آن از stdin استفاده می‌شود.

پیش‌فرض‌های تحت مالکیت Plugin

پیش‌فرض‌های بک‌اند CLI بخشی از سطح Plugin هستند:

• Pluginها آن‌ها را با api.registerCliBackend(...) ثبت می‌کنند.
• id بک‌اند به پیشوند ارائه‌دهنده در ارجاع‌های مدل تبدیل می‌شود.
• رفتار فرمان، argv، محیط، تجزیه‌گر، نشست و ناظر در کد Plugin باقی می‌ماند.
• عادی‌سازی مختص بک‌اند از طریق هوک اختیاری normalizeConfig تحت مالکیت Plugin باقی می‌ماند.

Anthropic مالک claude-cli و Google مالک google-gemini-cli است. اجراهای عامل OpenAI Codex از طریق openai/* از مهار app-server مربوط به Codex استفاده می‌کنند؛ OpenClaw دیگر بک‌اند همراه codex-cli را ثبت نمی‌کند.

Plugin همراه Anthropic برای claude-cli ثبت می‌شود:

Plugin همراه Google برای google-gemini-cli ثبت می‌شود:

پیش‌نیاز: Gemini CLI محلی باید نصب شده و در PATH با نام gemini موجود باشد (brew install gemini-cli یا npm install -g @google/gemini-cli).

نکات خروجی Gemini CLI:

• تجزیه‌گر پیش‌فرض stream-json رویدادهای message دستیار، رویدادهای ابزار، میزان مصرف نهایی result و رویدادهای خطای مهلک Gemini را می‌خواند.
• هنگامی که usage وجود ندارد یا خالی است، میزان مصرف به stats بازمی‌گردد؛ stats.cached به cacheRead در OpenClaw عادی‌سازی می‌شود و اگر stats.input وجود نداشته باشد، توکن‌های ورودی از stats.input_tokens - stats.cached محاسبه می‌شوند.

هم‌پوشانی‌های تبدیل متن

Pluginهایی که به سازگارسازهای کوچک برای پرامپت یا پیام نیاز دارند، می‌توانند بدون جایگزین‌کردن ارائه‌دهنده یا بک‌اند CLI، تبدیل‌های متن دوسویه اعلام کنند:

api.registerTextTransforms({  input: [{ from: /red basket/g, to: "blue basket" }],  output: [{ from: /blue basket/g, to: "red basket" }],});

input پرامپت سیستمی و پرامپت کاربر ارسال‌شده به CLI را بازنویسی می‌کند. output پیش از آن‌که OpenClaw نشانگرهای کنترلی و تحویل کانال خود را پردازش کند، متن جریانی دستیار و متن نهایی تجزیه‌شده را بازنویسی می‌کند؛ برای فراخوانی‌های مدل مبتنی بر ارائه‌دهنده نیز پس از ترمیم جریان و پیش از اجرای ابزار، مقادیر رشته‌ای داخل آرگومان‌های ساختاریافتهٔ فراخوانی ابزار را بازیابی می‌کند. قطعه‌های خام JSON ارائه‌دهنده بدون تغییر باقی می‌مانند؛ مصرف‌کنندگان باید از بار دادهٔ ساختاریافتهٔ جزئی، پایانی یا نتیجه استفاده کنند.

برای CLIهایی که رویدادهای JSONL مختص ارائه‌دهنده منتشر می‌کنند، jsonlDialect را در پیکربندی آن بک‌اند تنظیم کنید: claude-stream-json برای جریان‌های سازگار با Claude Code و gemini-stream-json برای رویدادهای stream-json مربوط به Gemini CLI.

مالکیت Compaction بومی

برخی بک‌اندهای CLI عاملی را اجرا می‌کنند که رونوشت خود را Compaction می‌کند؛ بنابراین OpenClaw نباید خلاصه‌ساز حفاظتی خود را روی آن‌ها اجرا کند، زیرا این کار با Compaction خود بک‌اند تداخل دارد و ممکن است نوبت را با خطای قطعی متوقف کند.

claude-cli هیچ نقطهٔ پایانی مهاری ندارد (Claude Code درون خود Compaction را انجام می‌دهد)، بنابراین ownsNativeCompaction: true را اعلام می‌کند و مسیر Compaction در OpenClaw ورودی نشست را بدون تغییر بازمی‌گرداند. OpenClaw بودجهٔ مؤثر زمینهٔ اجرا را از طریق CLAUDE_CODE_AUTO_COMPACT_WINDOW مستندشدهٔ Claude Code ارسال می‌کند تا Compaction خودکار بومی با محدودیت‌های پیکربندی‌شدهٔ contextTokens در Anthropic هم‌راستا بماند. نشست‌های مهار بومی مانند Codex همچنان به نقطهٔ پایانی Compaction مهار خود هدایت می‌شوند.

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

ownsNativeCompaction را فقط برای بک‌اندی اعلام کنید که واقعاً مالک Compaction است: باید رونوشت خود را به‌طور قابل‌اعتماد نزدیک پنجرهٔ زمینه محدود کند و یک نشست قابل‌ازسرگیری (برای مثال --resume / --session-id) را ماندگار سازد؛ در غیر این صورت، نشست به‌تعویق‌افتاده ممکن است همچنان از بودجه فراتر بماند.

هم‌پوشانی‌های MCP بسته

بک‌اندهای CLI فراخوانی‌های ابزار OpenClaw را مستقیماً دریافت نمی‌کنند، اما یک بک‌اند می‌تواند با bundleMcp: true استفاده از هم‌پوشانی پیکربندی MCP تولیدشده را فعال کند. رفتار همراه کنونی:

• claude-cli: فایل پیکربندی سخت‌گیرانهٔ MCP تولیدشده.
• google-gemini-cli: فایل تنظیمات سیستمی Gemini تولیدشده.

هنگامی که MCP بسته فعال است، OpenClaw:

• یک سرور HTTP MCP حلقهٔ بازگشتی راه‌اندازی می‌کند که ابزارهای Gateway را در اختیار فرایند CLI قرار می‌دهد و با مجوز زمینه‌ای مختص هر اجرا (OPENCLAW_MCP_TOKEN) احراز هویت می‌شود که فقط برای تلاش اجرای فعلی فعال است؛
• به‌جای اعتماد به سرآیندهای فرایند فرزند، دسترسی ابزار را به نشست، حساب و زمینهٔ کانال انتخاب‌شده توسط Gateway محدود می‌کند؛
• سرورهای فعال MCP بسته را برای فضای کاری فعلی بارگذاری و با هر شکل موجود پیکربندی یا تنظیمات MCP بک‌اند ادغام می‌کند؛
• پیکربندی راه‌اندازی را با استفاده از حالت یکپارچه‌سازی تحت مالکیت بک‌اند در Plugin مالک بازنویسی می‌کند.

اجرای محدود، مانند کارهای cron با toolsAllow، به ترجمه‌ای دقیق و تحت مالکیت بک‌اند نیاز دارد. بک‌اند همراه claude-cli ابزارهای بومی Claude و سفارشی‌سازی‌های کاربر، پروژه و محلی، از جمله هوک‌ها، Pluginها، عامل‌ها، Skills و CLAUDE.md را غیرفعال می‌کند. سپس همه ابزارهای مجاز OpenClaw را از طریق سرور MCP محدودشده به مجوز در دسترس قرار می‌دهد. با این کار، سیاست فایل‌سیستم، فرایند، exec، تأیید و سندباکس درون OpenClaw باقی می‌ماند، به‌جای آنکه دامنه اختیار به ابزارهای بومی Claude یا فرایندهای سفارشی‌سازی گسترش یابد. همان فهرست MCP هم در پیکربندی تولیدشده Claude و هم دوباره توسط Gateway هنگام فهرست‌کردن و اجرای ابزارها اعمال می‌شود. پیش از صدور مجوز، هسته ترجمه‌های بک‌اندی را که هرگونه مجوز MCP خارج از فهرست مجاز اولیه را نام ببرند، رد می‌کند. بک‌اندهای فاقد ترجمه دقیق همچنان به‌صورت بسته شکست می‌خورند.

اگر هیچ سرور MCP فعال نباشد، وقتی بک‌اند استفاده از MCP همراه را انتخاب می‌کند، OpenClaw همچنان یک پیکربندی سخت‌گیرانه تزریق می‌کند تا اجراهای پس‌زمینه ایزوله بمانند.

زمان‌اجرای MCP همراهِ محدود به نشست، برای استفاده مجدد در همان نشست کش می‌شوند و سپس پس از 10 دقیقه بی‌کاری پاک‌سازی می‌شوند. اجراهای تعبیه‌شده یک‌باره، مانند بررسی‌های احراز هویت، تولید slug و بازیابی active-memory، در پایان اجرا پاک‌سازی را درخواست می‌کنند تا فرایندهای فرزند stdio و جریان‌های Streamable HTTP/SSE بیشتر از اجرای مربوطه دوام نیاورند.

برای claude-cli، یک پروفایل OAuth/توکن سازگار OpenClaw که انتخاب یا مرتب شده است، به آن فرایند فرزند Claude ارسال می‌شود. بدین‌ترتیب، پروفایل‌های هر عامل برای آن نوبت مرجع اصلی می‌شوند، درحالی‌که اگر پروفایل سازگاری وجود نداشته باشد، ورود بومی Claude در میزبان حفظ می‌شود.

سقف تاریخچه بذرگذاری مجدد

وقتی یک نشست تازه CLI از رونوشت پیشین OpenClaw بذرگذاری می‌شود (برای مثال پس از تلاش مجدد session_expired)، اندازه بلوک رندرشده <conversation_history> محدود می‌شود تا پرامپت‌های بذرگذاری مجدد بیش‌ازحد بزرگ نشوند. مقدار پیش‌فرض 12,288 نویسه (حدود 3,000 توکن) است.

بک‌اندهای Claude CLI به‌جای آن، این سقف را متناسب با پنجره زمینه حل‌شده Claude تنظیم می‌کنند: پنجره‌های زمینه بزرگ‌تر، تا یک سقف ثابت، بخش بزرگ‌تری از تاریخچه قبلی را دریافت می‌کنند؛ سایر بک‌اندهای CLI مقدار پیش‌فرض محافظه‌کارانه را حفظ می‌کنند. این سقف فقط بلوک تاریخچه قبلی در پرامپت بذرگذاری مجدد را کنترل می‌کند.

محدودیت‌ها

• OpenClaw فراخوانی ابزارها را به پروتکل بک‌اند CLI تزریق نمی‌کند. بک‌اندها فقط وقتی ابزارهای Gateway را می‌بینند که استفاده از bundleMcp: true را انتخاب کنند.
• استریم به بک‌اند وابسته است: برخی بک‌اندها JSONL را به‌صورت استریم ارسال می‌کنند و برخی دیگر تا زمان خروج بافر می‌کنند.
• خروجی‌های ساخت‌یافته به قالب JSON خود CLI وابسته‌اند.

عیب‌یابی

مرتبط

• راهنمای عملیاتی Gateway
• مدل‌های محلی