--- read_when: - وقتی ارائه‌دهندگان API با مشکل مواجه می‌شوند، به یک راهکار جایگزین قابل‌اعتماد نیاز دارید - شما CLIهای محلی هوش مصنوعی را اجرا می‌کنید و می‌خواهید دوباره از آن‌ها استفاده کنید - می‌خواهید پل بازگشتی MCP را برای دسترسی به ابزارهای پشتیبان CLI درک کنید summary: 'بک‌اندهای CLI: جایگزین محلی CLI هوش مصنوعی با پل اختیاری ابزار MCP' title: بک‌اندهای CLI x-i18n: generated_at: "2026-07-12T09:59:04Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 119b503d3107672c1bd7ccc39b464f253138d0d63d175018e91cbaeb720c462f source_path: gateway/cli-backends.md workflow: 16 --- OpenClaw می‌تواند هنگامی که ارائه‌دهندگان API از دسترس خارج‌اند، با محدودیت نرخ مواجه شده‌اند یا درست عمل نمی‌کنند، یک CLI محلی هوش مصنوعی را به‌عنوان مسیر جایگزینِ صرفاً متنی اجرا کند. این قابلیت عمداً محافظه‌کارانه طراحی شده است: - ابزارهای OpenClaw مستقیماً تزریق نمی‌شوند، اما یک بک‌اند با `bundleMcp: true` می‌تواند ابزارهای Gateway را از طریق یک پل MCP مبتنی بر local loopback دریافت کند. - پخش جریانی 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 را زنده نگه می‌دارد و نوبت‌های پیگیری را از طریق ورودی استاندارد stream-json ارسال می‌کند. 4. خروجی را (JSON یا متن ساده) تجزیه و متن نهایی را بازمی‌گرداند. 5. شناسه‌های نشست را برای هر بک‌اند ماندگار می‌کند تا پیگیری‌ها همان نشست CLI را دوباره استفاده کنند. ### جزئیات Claude CLI بک‌اند همراه `claude-cli` حل‌کنندهٔ بومی skill در Claude Code را ترجیح می‌دهد. وقتی نمای لحظه‌ای Skills فعلی دست‌کم یک skill انتخاب‌شده با مسیری ایجادشده داشته باشد، OpenClaw یک Plugin موقت Claude Code را از طریق `--plugin-dir` ارسال می‌کند و فهرست تکراری Skills متعلق به OpenClaw را از پرامپت سیستمی افزوده‌شده حذف می‌کند. بدون یک skill پلاگینی با مسیر ایجادشده، OpenClaw فهرست پرامپت را به‌عنوان مسیر جایگزین نگه می‌دارد. بازنویسی‌های متغیر محیطی/کلید API مربوط به skill همچنان برای محیط فرایند فرزند در آن اجرا اعمال می‌شوند. Claude CLI حالت مجوز غیرتعاملی خودش را دارد؛ OpenClaw به‌جای افزودن پیکربندی ویژهٔ Claude، آن را به سیاست اجرای موجود نگاشت می‌کند. برای نشست‌های زندهٔ Claude تحت مدیریت OpenClaw، سیاست اجرای مؤثر مرجع نهایی است: حالت YOLO (`tools.exec.security: "full"` و `tools.exec.ask: "off"`) Claude را با `--permission-mode bypassPermissions` اجرا می‌کند، درحالی‌که سیاست محدودکننده آن را با `--permission-mode default` اجرا می‌کند. تنظیمات `agents.list[].tools.exec` مختص هر عامل، مقدار سراسری `tools.exec` را برای همان عامل بازنویسی می‌کنند. آرگومان‌های خام بک‌اند همچنان می‌توانند شامل `--permission-mode` باشند، اما اجرای زندهٔ Claude این پرچم را مطابق سیاست مؤثر یکسان‌سازی می‌کند. این بک‌اند همچنین سطوح `/think` متعلق به OpenClaw را به پرچم بومی `--effort` در Claude Code نگاشت می‌کند: `minimal`/`low` به `low`، مقدار `medium` به `medium`، و مقادیر `high`/`xhigh`/`max` مستقیماً عبور داده می‌شوند. مقدار `adaptive` پرچم‌های پیکربندی‌شدهٔ `--effort` را حذف می‌کند و جایگزینی ارائه نمی‌دهد، بنابراین Claude Code میزان تلاش مؤثر را بر اساس محیط، تنظیمات و مقادیر پیش‌فرض مدل خودش تعیین می‌کند. برای اینکه `/think` بر CLI ایجادشده اثر بگذارد، سایر بک‌اندهای CLI باید Plugin مالک خود را وادار کنند که یک نگاشت‌گر معادل برای 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 را حفظ می‌کنند: به‌طور پیش‌فرض ۸ مگابایت و ۲۰٬۰۰۰ خط خام JSONL در هر نوبت. می‌توانید آن‌ها را برای هر بک‌اند با `agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars` و `maxTurnLines` افزایش دهید؛ OpenClaw این تنظیمات را به ۶۴ مگابایت و ۱۰۰٬۰۰۰ خط محدود می‌کند. - نشست‌های ذخیره‌شدهٔ 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` را ترجیح می‌دهد و سپس جدیدترین نوبت‌های پس از مرز را تا سقف بودجهٔ نویسه اضافه می‌کند. نوبت‌های پیش از مرز حذف می‌شوند، زیرا خلاصه از قبل آن‌ها را بازنمایی می‌کند. - بلوک‌های ابزار برای حفظ واقع‌بینانهٔ بودجهٔ پرامپت، در راهنماهای فشردهٔ `(فراخوانی ابزار: نام)` و `(نتیجهٔ ابزار: …)` ادغام می‌شوند؛ خلاصهٔ بیش‌ازحد بزرگ کوتاه و با `(کوتاه‌شده)` برچسب‌گذاری می‌شود. - مسیرهای جایگزین `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"` پرامپت را از طریق stdin ارسال می‌کند. - اگر پرامپت بسیار طولانی باشد و `maxPromptArgChars` تنظیم شده باشد، به‌جای آن از stdin استفاده می‌شود. ## پیش‌فرض‌های تحت مالکیت Plugin پیش‌فرض‌های بک‌اند CLI بخشی از سطح Plugin هستند: - Pluginها آن‌ها را با `api.registerCliBackend(...)` ثبت می‌کنند. - `id` بک‌اند به پیشوند ارائه‌دهنده در ارجاع‌های مدل تبدیل می‌شود. - پیکربندی کاربر در `agents.defaults.cliBackends.` همچنان مقدار پیش‌فرض Plugin را بازنویسی می‌کند. - پاک‌سازی پیکربندی ویژهٔ بک‌اند از طریق قلاب اختیاری `normalizeConfig` در مالکیت Plugin باقی می‌ماند. مالک `claude-cli` شرکت Anthropic و مالک `google-gemini-cli` شرکت Google است. اجراهای عامل 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 Code مقدار `claude-stream-json` و برای رویدادهای `stream-json` در Gemini CLI مقدار `gemini-stream-json`. ## مالکیت Compaction بومی برخی بک‌اندهای CLI عاملی را اجرا می‌کنند که رونوشت خودش را Compaction می‌کند؛ بنابراین OpenClaw نباید خلاصه‌ساز محافظتی خود را روی آن‌ها اجرا کند—این کار با Compaction خود بک‌اند تداخل پیدا می‌کند و ممکن است نوبت را با خطای قطعی متوقف کند. `claude-cli` نقطهٔ پایانی هارنس ندارد (Claude Code به‌صورت داخلی Compaction را انجام می‌دهد)، بنابراین `ownsNativeCompaction: true` را تعریف می‌کند و مسیر Compaction در OpenClaw ورودی نشست را بدون تغییر بازمی‌گرداند. در مقابل، نشست‌های دارای هارنس بومی مانند 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 روی local loopback راه‌اندازی می‌کند که ابزارهای Gateway را در اختیار فرایند CLI قرار می‌دهد و با مجوز زمینهٔ مختص هر اجرا (`OPENCLAW_MCP_TOKEN`) احراز هویت می‌شود که فقط برای تلاش اجرایی فعلی فعال است؛ - به‌جای اعتماد به سرآیندهای فرایند فرزند، دسترسی ابزار را به زمینهٔ نشست، حساب و کانال انتخاب‌شده توسط Gateway مقید می‌کند؛ - سرورهای فعال MCP همراه را برای فضای کاری فعلی بارگیری کرده و با هر ساختار پیکربندی/تنظیمات MCP موجود در بک‌اند ادغام می‌کند؛ - پیکربندی راه‌اندازی را با استفاده از حالت یکپارچه‌سازی متعلق به بک‌اند که توسط Plugin مالک تعیین شده است، بازنویسی می‌کند. اگر هیچ سرور MCP فعالی وجود نداشته باشد، وقتی بک‌اند استفاده از MCP همراه را فعال کرده باشد OpenClaw همچنان یک پیکربندی سخت‌گیرانه تزریق می‌کند تا اجراهای پس‌زمینه ایزوله باقی بمانند. زمان‌اجرای MCP همراهِ محدود به نشست برای استفادهٔ مجدد درون همان نشست در حافظهٔ نهان نگه‌داری می‌شود و سپس پس از `mcp.sessionIdleTtlMs` میلی‌ثانیه بی‌کاری پاک‌سازی می‌شود (پیش‌فرض ۱۰ دقیقه؛ برای غیرفعال‌کردن مقدار `0` را تنظیم کنید). اجراهای تعبیه‌شدهٔ یک‌باره، مانند بررسی‌های احراز هویت، تولید نامک و بازیابی Active Memory، در پایان اجرا درخواست پاک‌سازی می‌کنند تا فرایندهای فرزند stdio و جریان‌های HTTP/SSE قابل‌جریان بیشتر از اجرای مربوطه زنده نمانند. ## سقف تاریخچهٔ بذرگذاری مجدد وقتی یک نشست تازهٔ CLI از رونوشت پیشین OpenClaw بذرگذاری می‌شود (برای مثال پس از تلاش مجدد ناشی از `session_expired`)، اندازهٔ بلوک رندرشدهٔ `` محدود می‌شود تا اعلان‌های بذرگذاری مجدد بیش‌ازحد بزرگ نشوند. مقدار پیش‌فرض ۱۲٬۲۸۸ نویسه (حدود ۳٬۰۰۰ توکن) است. بک‌اندهای Claude CLI این سقف را بر اساس پنجرهٔ زمینهٔ تعیین‌شدهٔ Claude مقیاس می‌کنند: پنجره‌های زمینهٔ بزرگ‌تر بخش بزرگ‌تری از تاریخچهٔ قبلی را تا یک سقف ثابت دریافت می‌کنند؛ سایر بک‌اندهای CLI مقدار پیش‌فرض محافظه‌کارانه را حفظ می‌کنند. این سقف فقط بلوک تاریخچهٔ قبلی در اعلان بذرگذاری مجدد را کنترل می‌کند—محدودیت‌های خروجی نشست زنده به‌طور جداگانه در `reliability.outputLimits` تنظیم می‌شوند (به [نشست‌ها](#sessions) مراجعه کنید). ## محدودیت‌ها - بدون فراخوانی مستقیم ابزارهای OpenClaw: OpenClaw فراخوانی ابزار را به پروتکل بک‌اند CLI تزریق نمی‌کند. بک‌اندها فقط وقتی `bundleMcp: true` را فعال کنند، ابزارهای Gateway را می‌بینند. - جریان‌دهی مختص بک‌اند است: برخی بک‌اندها JSONL را به‌صورت جریانی ارسال می‌کنند و برخی دیگر تا خروج بافر می‌کنند. - خروجی‌های ساختاریافته به قالب JSON خود CLI وابسته‌اند. ## عیب‌یابی | نشانه | راه‌حل | | --------------------- | ----------------------------------------------------------------- | | CLI پیدا نشد | `command` را روی یک مسیر کامل تنظیم کنید. | | نام مدل نادرست | برای نگاشت `provider/model` به شناسهٔ مدل CLI از `modelAliases` استفاده کنید. | | نبود تداوم نشست | مطمئن شوید `sessionArg` تنظیم شده و `sessionMode` برابر `none` نیست. | | تصاویر نادیده گرفته می‌شوند | `imageArg` را تنظیم کنید و بررسی کنید CLI از مسیر فایل‌ها پشتیبانی می‌کند. | ## مرتبط - [راهنمای عملیاتی Gateway](/fa/gateway) - [مدل‌های محلی](/fa/gateway/local-models)