--- read_when: - وقتی ارائه‌دهندگان API با مشکل مواجه می‌شوند، به یک راهکار جایگزین مطمئن نیاز دارید - شما CLIهای هوش مصنوعی را به‌صورت محلی اجرا می‌کنید و می‌خواهید دوباره از آن‌ها استفاده کنید - می‌خواهید پل بازگشتی MCP برای دسترسی به ابزارهای بک‌اند CLI را درک کنید summary: 'بک‌اندهای CLI: جایگزین محلی CLI هوش مصنوعی با پل اختیاری ابزار MCP' title: بک‌اندهای CLI x-i18n: generated_at: "2026-07-16T16:09:52Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: ffeb19e582819f511212326da83381ba2c52e9f5743263f1ef9e0dc0fbbaf08e source_path: gateway/cli-backends.md workflow: 16 --- OpenClaw می‌تواند هنگامی که ارائه‌دهندگان API از دسترس خارج شده‌اند، با محدودیت نرخ مواجه‌اند یا درست رفتار نمی‌کنند، یک CLI هوش مصنوعی محلی را به‌عنوان جایگزین صرفاً متنی اجرا کند. این قابلیت عمداً محافظه‌کارانه است: - ابزارهای OpenClaw مستقیماً تزریق نمی‌شوند، اما یک بک‌اند دارای `bundleMcp: true` می‌تواند ابزارهای Gateway را از طریق یک پل MCP حلقه‌بازگشتی دریافت کند. - استریم JSONL برای CLIهایی که از آن پشتیبانی می‌کنند. - نشست‌ها پشتیبانی می‌شوند، بنابراین نوبت‌های پیگیری منسجم باقی می‌مانند. - اگر CLI مسیرهای تصویر را بپذیرد، تصاویر منتقل می‌شوند. از آن به‌عنوان یک شبکه ایمنی برای پاسخ‌های متنی «همیشه کار می‌کند» استفاده کنید، نه مسیر اصلی. برای یک محیط اجرای کامل با کنترل‌های نشست ACP، وظایف پس‌زمینه، اتصال رشته/مکالمه و نشست‌های خارجی پایدار کدنویسی، به‌جای آن از [عامل‌های ACP](/fa/tools/acp-agents) استفاده کنید؛ بک‌اندهای CLI، ACP نیستند. در حال ساخت یک Plugin بک‌اند جدید هستید؟ [Pluginهای بک‌اند CLI](/fa/plugins/cli-backend-plugins) را ببینید. این صفحه پیکربندی و راهبری یک بک‌اند ازپیش‌ثبت‌شده را پوشش می‌دهد. ## شروع سریع Plugin همراه Anthropic یک بک‌اند پیش‌فرض `claude-cli` ثبت می‌کند، بنابراین به‌جز نصب‌بودن Claude Code و ورود به حساب در آن، به هیچ پیکربندی‌ای نیاز ندارد: ```bash openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6 ``` وقتی هیچ فهرست صریحی از عامل‌ها پیکربندی نشده باشد، `main` شناسه پیش‌فرض عامل است؛ در غیر این صورت شناسه عامل خود را جایگزین کنید. اگر Gateway تحت launchd/systemd و با یک `PATH` حداقلی اجرا می‌شود، باینری را صریحاً مشخص کنید: ```json5 { agents: { defaults: { cliBackends: { "claude-cli": { command: "/opt/homebrew/bin/claude", }, }, }, }, } ``` اگر از یک بک‌اند CLI همراه به‌عنوان ارائه‌دهنده اصلی پیام روی میزبان Gateway استفاده کنید، هنگامی که پیکربندی شما در یک مرجع مدل یا زیر `agents.defaults.cliBackends` به آن بک‌اند ارجاع دهد، OpenClaw به‌طور خودکار Plugin همراه مالک آن را بارگذاری می‌کند. ## استفاده به‌عنوان جایگزین بک‌اند CLI را به فهرست جایگزین‌های خود اضافه کنید تا فقط هنگام شکست مدل‌های اصلی اجرا شود: ```json5 { 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.models` به‌عنوان فهرست مجاز استفاده می‌کنید، مدل‌های بک‌اند CLI خود را نیز در آن بگنجانید. هنگامی که ارائه‌دهنده اصلی شکست می‌خورد (احراز هویت، محدودیت نرخ، پایان مهلت)، OpenClaw در مرحله بعد بک‌اند CLI را امتحان می‌کند. ## پیکربندی همه بک‌اندهای CLI زیر `agents.defaults.cliBackends` قرار می‌گیرند و با شناسه ارائه‌دهنده کلیدگذاری می‌شوند (برای مثال `claude-cli`، `my-cli`). شناسه ارائه‌دهنده به بخش چپ مرجع مدل تبدیل می‌شود: `/`. ```json5 { agents: { defaults: { cliBackends: { "my-cli": { command: "my-cli", args: ["--json"], output: "json", input: "arg", modelArg: "--model", modelAliases: { "claude-opus-4-6": "opus", "claude-sonnet-4-6": "sonnet", }, sessionArg: "--session", sessionMode: "existing", sessionIdFields: ["session_id", "conversation_id"], systemPromptArg: "--system", // پرچم اختصاصی فایل پرامپت: // systemPromptFileArg: "--system-file", // در عوض، پرچم بازنویسی پیکربندی به سبک Codex: // systemPromptFileConfigArg: "-c", // systemPromptFileConfigKey: "model_instructions_file", systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", // فقط زمانی فعال کنید که این بک‌اند مجاز باشد نشست‌های نامعتبرشده را // پیش از Compaction از تاریخچه خام و کران‌دار رونوشت OpenClaw دوباره مقداردهی اولیه کند. reseedFromRawTranscriptWhenUncompacted: true, serialize: true, }, }, }, }, } ``` ## نحوه کار 1. یک بک‌اند را بر اساس پیشوند ارائه‌دهنده (`claude-cli/...`) انتخاب می‌کند. 2. با استفاده از همان پرامپت OpenClaw و زمینه فضای کاری، یک پرامپت سیستمی می‌سازد. 3. CLI را با یک شناسه نشست (در صورت پشتیبانی) اجرا می‌کند تا تاریخچه سازگار بماند. بک‌اند همراه `claude-cli` برای هر نشست OpenClaw یک فرایند stdio متعلق به Claude را زنده نگه می‌دارد و نوبت‌های پیگیری را از طریق stdin با قالب stream-json ارسال می‌کند. 4. خروجی (JSON یا متن ساده) را تجزیه و متن نهایی را برمی‌گرداند. 5. شناسه‌های نشست را برای هر بک‌اند پایدار ذخیره می‌کند تا پیگیری‌ها از همان نشست CLI استفاده کنند. ### جزئیات ویژه Claude CLI بک‌اند همراه `claude-cli` حل‌کننده بومی مهارت Claude Code را ترجیح می‌دهد. هنگامی که اسنپ‌شات فعلی مهارت‌ها دست‌کم یک مهارت انتخاب‌شده با مسیر تحقق‌یافته داشته باشد، OpenClaw یک Plugin موقت Claude Code را از طریق `--plugin-dir` ارسال می‌کند و کاتالوگ تکراری مهارت‌های OpenClaw را از پرامپت سیستمی الحاق‌شده حذف می‌کند. بدون یک مهارت Plugin تحقق‌یافته، OpenClaw کاتالوگ پرامپت را به‌عنوان جایگزین نگه می‌دارد. بازنویسی‌های محیطی/کلید API مهارت همچنان برای محیط فرایند فرزند آن اجرا اعمال می‌شوند. Claude CLI حالت مجوز غیرتعاملی خودش را دارد؛ OpenClaw به‌جای افزودن پیکربندی ویژه Claude، آن را به خط‌مشی اجرای موجود نگاشت می‌کند. برای نشست‌های زنده Claude تحت مدیریت OpenClaw، خط‌مشی اجرای مؤثر مرجع نهایی است: YOLO (`tools.exec.security: "full"` و `tools.exec.ask: "off"`) معمولاً Claude را با `--permission-mode bypassPermissions` اجرا می‌کند، در حالی که یک خط‌مشی محدودکننده آن را با `--permission-mode default` اجرا می‌کند. Gatewayهایی که با کاربر root اجرا می‌شوند نیز از `default` استفاده می‌کنند، زیرا Claude Code حالت دورزدن را برای root رد می‌کند؛ OpenClaw همچنان بر اساس خط‌مشی اجرای پیکربندی‌شده به درخواست‌های کنترل ابزار stdio متعلق به Claude پاسخ می‌دهد. تنظیمات `agents.list[].tools.exec` مختص هر عامل، `tools.exec` سراسری را برای آن عامل بازنویسی می‌کنند. آرگومان‌های خام بک‌اند ممکن است همچنان شامل `--permission-mode` باشند، اما اجراهای زنده Claude آن پرچم را مطابق خط‌مشی مؤثر و محدودیت میزبان نرمال‌سازی می‌کنند. این بک‌اند همچنین سطوح `/think` در OpenClaw را به پرچم بومی `--effort` در Claude Code نگاشت می‌کند: `minimal`/`low` -> `low`، `medium` -> `medium`، و `high`/`xhigh`/`max` مستقیماً عبور داده می‌شوند. این کار سطوح تلاش پشتیبانی‌شده Fable 5 را برای Claude CLI مبتنی بر اشتراک و مسیرهای کلید API یکسان نگه می‌دارد. `adaptive` پرچم‌های پیکربندی‌شده `--effort` را حذف می‌کند و جایگزینی ارائه نمی‌دهد، بنابراین Claude Code تلاش مؤثر را از محیط، تنظیمات و پیش‌فرض‌های مدل خودش تعیین می‌کند. برای اینکه `/think` بر CLI ایجادشده اثر بگذارد، Plugin مالک سایر بک‌اندهای CLI باید یک نگاشت‌گر argv معادل تعریف کند. پیش از آنکه OpenClaw بتواند از `claude-cli` استفاده کند، خود Claude Code باید روی همان میزبان وارد حساب شده باشد: ```bash claude auth login claude auth status --text openclaw models auth login --provider anthropic --method cli --set-default ``` در نصب‌های Docker، Claude Code باید داخل خانه پایدار کانتینر نصب شده و وارد حساب شده باشد، نه فقط روی میزبان؛ [بک‌اند Claude CLI در Docker](/fa/install/docker#claude-cli-backend-in-docker) را ببینید. `agents.defaults.cliBackends.claude-cli.command` را فقط زمانی تنظیم کنید که باینری `claude` از قبل در `PATH` نباشد. ## نشست‌ها - اگر CLI از نشست‌ها پشتیبانی می‌کند، `sessionArg` (برای مثال `--session-id`) یا، هنگامی که شناسه باید در چند پرچم قرار گیرد، `sessionArgs` (جای‌نگهدار `{sessionId}`) را تنظیم کنید. - اگر CLI از یک زیرفرمان ازسرگیری با پرچم‌های متفاوت استفاده می‌کند، `resumeArgs` را تنظیم کنید (هنگام ازسرگیری جایگزین `args` می‌شود) و برای ازسرگیری‌های غیر JSON، در صورت نیاز `resumeOutput` را نیز تنظیم کنید. - `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 در هر نوبت. آن‌ها را برای هر بک‌اند با `agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars` و `maxTurnLines` افزایش دهید؛ OpenClaw این تنظیمات را به 64 MiB و 100,000 خط محدود می‌کند. - نشست‌های ذخیره‌شده 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` به یک گزینه غیر CLI در [`agents.defaults.model.fallbacks`](/fa/concepts/model-failover) منتقل می‌شود، 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 دوباره استفاده می‌کند، بنابراین مسیرهای دلخواه قابل خواندن نیستند. ## تصاویر اگر CLI شما مسیرهای تصویر را می‌پذیرد، `imageArg` را تنظیم کنید: ```json5 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` استفاده می‌کند؛ بازنویسی‌های قدیمی `--output-format json` همچنان از تجزیه‌کننده JSON استفاده می‌کنند. حالت‌های ورودی: - `input: "arg"` (پیش‌فرض) پرامپت را به‌عنوان آخرین آرگومان CLI ارسال می‌کند. - `input: "stdin"` پرامپت را از طریق ورودی استاندارد ارسال می‌کند. - اگر پرامپت بسیار طولانی باشد و `maxPromptArgChars` تنظیم شده باشد، به‌جای آن از ورودی استاندارد استفاده می‌شود. ## پیش‌فرض‌های تحت مالکیت Plugin پیش‌فرض‌های بک‌اند CLI بخشی از سطح Plugin هستند: - Pluginها آن‌ها را با `api.registerCliBackend(...)` ثبت می‌کنند. - مقدار `id` بک‌اند، پیشوند ارائه‌دهنده در ارجاع‌های مدل می‌شود. - پیکربندی کاربر در `agents.defaults.cliBackends.` همچنان پیش‌فرض Plugin را لغو می‌کند. - پاک‌سازی پیکربندی مختص بک‌اند، از طریق هوک اختیاری `normalizeConfig` تحت مالکیت Plugin باقی می‌ماند. Anthropic مالک `claude-cli` و Google مالک `google-gemini-cli` است. اجراهای عامل OpenAI Codex از مهار app-server مربوط به Codex از طریق `openai/*` استفاده می‌کنند؛ OpenClaw دیگر بک‌اند همراه `codex-cli` را ثبت نمی‌کند. Plugin همراه Anthropic برای `claude-cli` ثبت می‌شود: | کلید | مقدار | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `command` | `claude` | | `args` | `-p --output-format stream-json --include-partial-messages --verbose --setting-sources user --allowedTools mcp__openclaw__* --disallowedTools ScheduleWakeup,CronCreate,Bash(run_in_background:true),Monitor` | | `output` | `jsonl` | | `input` | `stdin` | | `modelArg` | `--model` | | `sessionArg` | `--session-id` | | `sessionMode` | `always` | | `imageArg` | `@` | | `imagePathScope` | `workspace` | | `systemPromptFileArg` | `--append-system-prompt-file` | | `systemPromptMode` | `append` | Plugin همراه Google برای `google-gemini-cli` ثبت می‌شود: | کلید | مقدار | | ------------------------- | -------------------------------------------------------------------------------------- | | `command` | `gemini` | | `args` | `--skip-trust --approval-mode auto_edit --output-format stream-json --prompt {prompt}` | | `resumeArgs` | همان، با `--resume {sessionId}` | | `output` / `resumeOutput` | `jsonl` | | `jsonlDialect` | `gemini-stream-json` | | `imageArg` | `@` | | `imagePathScope` | `workspace` | | `modelArg` | `--model` | | `sessionMode` | `existing` | | `sessionIdFields` | `["session_id", "sessionId"]` | پیش‌نیاز: Gemini CLI محلی باید نصب شده و با نام `gemini` در `PATH` موجود باشد (`brew install gemini-cli` یا `npm install -g @google/gemini-cli`). نکات خروجی Gemini CLI: - تجزیه‌گر پیش‌فرض `stream-json` رویدادهای `message` دستیار، رویدادهای ابزار، میزان استفاده نهایی `result` و رویدادهای خطای مهلک Gemini را می‌خواند. - اگر آرگومان‌های Gemini را به `--output-format json` تغییر دهید، OpenClaw آن بک‌اند را دوباره به `output: "json"` عادی‌سازی می‌کند و متن پاسخ را از فیلد `response` در JSON می‌خواند. - وقتی `usage` وجود نداشته یا خالی باشد، میزان استفاده به `stats` بازمی‌گردد؛ `stats.cached` به `cacheRead` در OpenClaw عادی‌سازی می‌شود و اگر `stats.input` وجود نداشته باشد، توکن‌های ورودی از `stats.input_tokens - stats.cached` محاسبه می‌شوند. پیش‌فرض‌ها را فقط در صورت نیاز تغییر دهید (رایج‌ترین مورد، یک مسیر مطلق `command` است). ## هم‌پوشانی‌های تبدیل متن Pluginهایی که به سازگارسازهای کوچک برای سازگاری پرامپت/پیام نیاز دارند، می‌توانند بدون جایگزینی ارائه‌دهنده یا بک‌اند CLI، تبدیل‌های متنی دوسویه تعریف کنند: ```typescript 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 عاملی را اجرا می‌کنند که رونوشت خود را فشرده می‌کند، بنابراین OpenClaw نباید خلاصه‌ساز حفاظتی خود را روی آن‌ها اجرا کند؛ انجام این کار با Compaction خود بک‌اند تداخل دارد و می‌تواند نوبت را با خطای قطعی متوقف کند. `claude-cli` هیچ نقطه پایانی مهاری ندارد (Claude Code به‌صورت داخلی Compaction را انجام می‌دهد)، بنابراین `ownsNativeCompaction: true` را اعلام می‌کند و مسیر Compaction در OpenClaw ورودی نشست را بدون تغییر برمی‌گرداند. OpenClaw بودجه مؤثر زمینه اجرا را از طریق [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](https://code.claude.com/docs/en/env-vars) مستندشده Claude Code منتقل می‌کند و Compaction خودکار بومی را با محدودیت‌های پیکربندی‌شده `contextTokens` در Anthropic هم‌تراز نگه می‌دارد. در مقابل، نشست‌های دارای مهار بومی مانند Codex همچنان به نقطه پایانی Compaction مهار خود هدایت می‌شوند. ```typescript 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 مالک بازنویسی می‌کند. اگر هیچ سرور MCP فعالی وجود نداشته باشد، وقتی بک‌اندی استفاده از MCP بسته را فعال کرده باشد، OpenClaw همچنان یک پیکربندی سخت‌گیرانه تزریق می‌کند تا اجراهای پس‌زمینه ایزوله باقی بمانند. محیط‌های اجرای همراه MCP با دامنه نشست برای استفاده مجدد درون نشست ذخیره موقت می‌شوند و سپس پس از `mcp.sessionIdleTtlMs` میلی‌ثانیه بی‌کاری جمع‌آوری می‌شوند (پیش‌فرض 10 دقیقه؛ برای غیرفعال‌کردن، `0` را تنظیم کنید). اجراهای تعبیه‌شده یک‌باره مانند بررسی‌های احراز هویت، تولید نامک و بازیابی Active Memory درخواست می‌کنند در پایان اجرا پاک‌سازی انجام شود تا فرایندهای فرزند ورودی/خروجی استاندارد و جریان‌های HTTP/SSE قابل‌استریم بیش از عمر اجرا باقی نمانند. ## سقف تاریخچه بازبذرگذاری هنگامی که یک نشست تازه CLI از رونوشت قبلی OpenClaw بذرگذاری می‌شود (برای مثال پس از تلاش مجدد `session_expired`)، بلوک رندرشده `` محدود می‌شود تا اندازه پرامپت‌های بازبذرگذاری به‌شدت افزایش نیابد. مقدار پیش‌فرض 12,288 نویسه (حدود 3,000 توکن) است. بک‌اندهای Claude CLI در عوض این سقف را متناسب با پنجره زمینه حل‌شده Claude مقیاس می‌کنند: پنجره‌های زمینه بزرگ‌تر، بخش بزرگ‌تری از تاریخچه قبلی را تا یک سقف ثابت دریافت می‌کنند؛ سایر بک‌اندهای CLI همان مقدار پیش‌فرض محافظه‌کارانه را حفظ می‌کنند. این سقف فقط بلوک تاریخچه قبلی در پرامپت بازبذرگذاری را کنترل می‌کند؛ محدودیت‌های خروجی نشست زنده به‌صورت جداگانه در `reliability.outputLimits` تنظیم می‌شوند (به [نشست‌ها](#sessions) مراجعه کنید). ## محدودیت‌ها - بدون فراخوانی مستقیم ابزار OpenClaw: ‏OpenClaw فراخوانی‌های ابزار را به پروتکل بک‌اند CLI تزریق نمی‌کند. بک‌اندها فقط هنگامی ابزارهای Gateway را می‌بینند که استفاده از `bundleMcp: true` را فعال کنند. - جریان‌دهی مختص بک‌اند است: برخی بک‌اندها JSONL را به‌صورت جریانی ارسال می‌کنند و برخی دیگر تا زمان خروج آن را در بافر نگه می‌دارند. - خروجی‌های ساخت‌یافته به قالب JSON خود CLI وابسته‌اند. ## عیب‌یابی | نشانه | راه‌حل | | --------------------- | ----------------------------------------------------------------- | | CLI یافت نشد | `command` را روی یک مسیر کامل تنظیم کنید. | | نام مدل نادرست | از `modelAliases` برای نگاشت `provider/model` به شناسه مدل CLI استفاده کنید. | | نبود تداوم نشست | مطمئن شوید `sessionArg` تنظیم شده و `sessionMode` برابر با `none` نیست. | | تصاویر نادیده گرفته می‌شوند | `imageArg` را تنظیم و پشتیبانی CLI از مسیر فایل‌ها را تأیید کنید. | ## مطالب مرتبط - [راهنمای عملیاتی Gateway](/fa/gateway) - [مدل‌های محلی](/fa/gateway/local-models)