مدل‌های محلی

مدل‌های محلی کار می‌کنند، اما سطح نیازمندی‌های سخت‌افزار، اندازهٔ کانتکست و دفاع در برابر تزریق پرامپت را بالا می‌برند: مدل‌های کوچک یا به‌شدت کوانتیزه‌شده کانتکست را کوتاه می‌کنند و فیلترهای ایمنی سمت ارائه‌دهنده را نادیده می‌گیرند. این صفحه پشته‌های محلی رده‌بالا و سرورهای سفارشی سازگار با OpenAI را پوشش می‌دهد. برای مسیری با کمترین اصطکاک، با LM Studio یا Ollama و openclaw onboard شروع کنید.

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

حداقل سخت‌افزار

برای داشتن چرخهٔ عامل روان، بیش از 2 دستگاه Mac Studio با بالاترین پیکربندی یا یک سامانهٔ GPU معادل (~$30k+) را هدف بگیرید. یک GPU با 24 GB فقط از پس پرامپت‌های سبک‌تر با تأخیر بیشتر برمی‌آید. همیشه بزرگ‌ترین گونه / گونهٔ کامل قابل میزبانی را اجرا کنید؛ چک‌پوینت‌های کوچک یا به‌شدت کوانتیزه‌شده خطر تزریق پرامپت را افزایش می‌دهند (به امنیت مراجعه کنید).

انتخاب بک‌اند

وقتی بک‌اند از api: "openai-responses" پشتیبانی می‌کند، از آن استفاده کنید (LM Studio پشتیبانی می‌کند). در غیر این صورت از api: "openai-completions" استفاده کنید. اگر api در یک ارائه‌دهندهٔ سفارشی دارای baseUrl حذف شود، مقدار پیش‌فرض OpenClaw برابر openai-completions خواهد بود.

LM Studio + مدل محلی بزرگ (Responses API)

این بهترین پشتهٔ محلی فعلی است. یک مدل بزرگ را در LM Studio بارگذاری کنید (نسخهٔ کامل Qwen، DeepSeek یا Llama)، سرور محلی را فعال کنید (پیش‌فرض http://127.0.0.1:1234) و با استفاده از Responses API استدلال را از متن نهایی جدا نگه دارید.

{  agents: {    defaults: {      model: { primary: "lmstudio/my-local-model" },      models: {        "anthropic/claude-opus-4-6": { alias: "Opus" },        "lmstudio/my-local-model": { alias: "Local" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

چک‌لیست راه‌اندازی:

• نصب LM Studio: https://lmstudio.ai
• بزرگ‌ترین نسخهٔ موجود مدل را دانلود کنید (از گونه‌های «کوچک»/به‌شدت کوانتیزه‌شده اجتناب کنید)، سرور را راه‌اندازی کنید و تأیید کنید که http://127.0.0.1:1234/v1/models آن را فهرست می‌کند.
• my-local-model را با شناسهٔ واقعی مدل نمایش‌داده‌شده در LM Studio جایگزین کنید.
• مدل را بارگذاری‌شده نگه دارید؛ بارگذاری سرد تأخیر راه‌اندازی را افزایش می‌دهد.
• اگر نسخهٔ LM Studio شما متفاوت است، contextWindow/maxTokens را تنظیم کنید.
• برای WhatsApp، از Responses API استفاده کنید تا فقط متن نهایی ارسال شود.
• models.mode: "merge" را حفظ کنید تا مدل‌های میزبانی‌شده به‌عنوان گزینه‌های بازگشت در دسترس بمانند.

پیکربندی ترکیبی: مدل میزبانی‌شدهٔ اصلی، مدل محلی جایگزین

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["lmstudio/my-local-model", "anthropic/claude-opus-4-6"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "lmstudio/my-local-model": { alias: "Local" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },  models: {    mode: "merge",    providers: {      lmstudio: {        baseUrl: "http://127.0.0.1:1234/v1",        apiKey: "lmstudio",        api: "openai-responses",        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,          },        ],      },    },  },}

برای اولویت‌دادن به مدل محلی همراه با شبکهٔ ایمنی میزبانی‌شده، ترتیب primary/fallbacks را جابه‌جا کنید و همان بلوک providers و models.mode: "merge" را حفظ کنید.

میزبانی منطقه‌ای / مسیریابی داده

گونه‌های میزبانی‌شدهٔ MiniMax/Kimi/GLM نیز در OpenRouter با نقاط پایانی مقید به منطقه (برای نمونه، میزبانی‌شده در ایالات متحده) وجود دارند. گونهٔ منطقه‌ای را انتخاب کنید تا ضمن حفظ models.mode: "merge" برای گزینه‌های بازگشت Anthropic/OpenAI، ترافیک در حوزهٔ قضایی انتخابی شما باقی بماند. استفادهٔ صرفاً محلی همچنان قوی‌ترین مسیر حفظ حریم خصوصی است؛ مسیریابی منطقه‌ای میزبانی‌شده زمانی گزینهٔ میانی است که به قابلیت‌های ارائه‌دهنده نیاز دارید، اما می‌خواهید جریان داده را کنترل کنید.

سایر پراکسی‌های محلی سازگار با OpenAI

MLX (mlx_lm.server)،‏ vLLM،‏ SGLang،‏ LiteLLM،‏ OAI-proxy یا هر Gateway سفارشی، در صورتی که یک نقطهٔ پایانی سبک OpenAI با /v1/chat/completions ارائه کند، کار می‌کند. مگر اینکه بک‌اند صراحتاً پشتیبانی از /v1/responses را مستند کرده باشد، از openai-completions استفاده کنید.

{  agents: {    defaults: {      model: { primary: "local/my-local-model" },    },  },  models: {    mode: "merge",    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-completions",        timeoutSeconds: 300,        models: [          {            id: "my-local-model",            name: "Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 120000,            maxTokens: 8192,          },        ],      },    },  },}

ورودی‌های ارائه‌دهندهٔ سفارشی/محلی برای درخواست‌های محافظت‌شدهٔ مدل، دقیقاً به مبدأ پیکربندی‌شدهٔ baseUrl خود اعتماد می‌کنند؛ از جمله میزبان حلقه‌ای، LAN،‏ tailnet و میزبان‌های DNS خصوصی. مبدأهای متادیتا/link-local همیشه و بدون توجه به تنظیمات مسدود می‌شوند. درخواست‌ها به سایر مبدأهای خصوصی همچنان به models.providers.<id>.request.allowPrivateNetwork: true نیاز دارند؛ برای انصراف از اعتماد به مبدأ دقیق، پرچم اعتماد را روی false تنظیم کنید.

models.providers.<id>.models[].id مختص ارائه‌دهنده است؛ پیشوند ارائه‌دهنده را در آن قرار ندهید. برای یک سرور MLX که با mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit راه‌اندازی شده است:

• models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"
• agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"

روی مدل‌های بینایی محلی یا پراکسی‌شده، input: ["text", "image"] را تنظیم کنید تا پیوست‌های تصویری به نوبت‌های عامل تزریق شوند. راه‌اندازی تعاملی ارائه‌دهندهٔ سفارشی شناسه‌های متداول مدل بینایی را استنباط می‌کند و فقط دربارهٔ نام‌های ناشناخته می‌پرسد؛ راه‌اندازی غیرتعاملی نیز با امکان بازنویسی از طریق --custom-image-input / --custom-text-input از همین استنباط استفاده می‌کند.

پیش از افزایش agents.defaults.timeoutSeconds، برای سرورهای مدل محلی/راه‌دور کند از models.providers.<id>.timeoutSeconds استفاده کنید. مهلت زمانی ارائه‌دهنده، اتصال، سرآیندها، استریم بدنه و لغو کلی واکشی محافظت‌شده را فقط برای درخواست‌های HTTP مدل پوشش می‌دهد؛ اگر مهلت زمانی عامل/اجرا کمتر است، آن را نیز افزایش دهید، زیرا مهلت زمانی ارائه‌دهنده نمی‌تواند کل اجرا را طولانی‌تر کند.

نکات رفتاری برای بک‌اندهای محلی/پراکسی‌شدهٔ /v1:

• OpenClaw این مسیرها را مسیرهای پراکسی‌مانند سازگار با OpenAI تلقی می‌کند، نه نقاط پایانی بومی OpenAI.
• شکل‌دهی درخواست مختص OpenAI بومی اعمال نمی‌شود: بدون service_tier، بدون Responses store، بدون شکل‌دهی محمولهٔ سازگاری استدلال OpenAI، بدون راهنمای کش پرامپت.
• سرآیندهای پنهان انتساب OpenClaw ‏(originator، version، User-Agent) در URLهای پراکسی سفارشی تزریق نمی‌شوند.

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

بازنویسی‌های سازگاری برای بک‌اندهای سخت‌گیرتر سازگار با OpenAI:

• محتوای فقط‌رشته‌ای: برخی سرورها فقط messages[].content رشته‌ای را می‌پذیرند، نه آرایه‌های ساختاریافتهٔ بخش‌های محتوا. models.providers.<provider>.models[].compat.requiresStringContent: true را تنظیم کنید.

• کلیدهای سخت‌گیرانهٔ پیام: اگر سرور ورودی‌های پیام دارای بیش از role/content را رد می‌کند، compat.strictMessageKeys: true را تنظیم کنید.

• متن ابزار داخل براکت: برخی مدل‌های محلی درخواست‌های مستقل ابزار را به‌شکل متن داخل براکت تولید می‌کنند، مانند [tool_name] که JSON و سپس [END_TOOL_REQUEST] آن را دنبال می‌کند. OpenClaw فقط زمانی آن‌ها را به فراخوانی واقعی ابزار ارتقا می‌دهد که نام دقیقاً با یک ابزار ثبت‌شده برای آن نوبت مطابقت داشته باشد؛ در غیر این صورت، به‌صورت متن پنهان و پشتیبانی‌نشده باقی می‌ماند.

• متن ساختارنیافتهٔ شبیه فراخوانی ابزار: اگر مدلی متنی به سبک JSON/XML/ReAct تولید کند که شبیه فراخوانی ابزار است، اما فراخوانی ساختاریافته نبوده، OpenClaw آن را به‌صورت متن باقی می‌گذارد و هشداری را با شناسهٔ اجرا، ارائه‌دهنده/مدل، الگوی شناسایی‌شده و در صورت موجود بودن نام ابزار ثبت می‌کند. این ناسازگاری ارائه‌دهنده/مدل است، نه اجرای تکمیل‌شدهٔ ابزار.

• اجبار به استفاده از ابزار: اگر ابزارها به‌صورت متن دستیار ظاهر می‌شوند (JSON/XML/ReAct خام یا آرایهٔ خالی tool_calls)، ابتدا تأیید کنید که قالب/تجزیه‌گر چت سرور از فراخوانی ابزار پشتیبانی می‌کند. اگر تجزیه‌گر فقط هنگام اجبار به استفاده از ابزار کار می‌کند، مقدار پیش‌فرض پراکسی tool_choice: "auto" را برای هر مدل بازنویسی کنید:

  {  agents: {    defaults: {      models: {        "local/my-local-model": {          params: {            extra_body: {              tool_choice: "required",            },          },        },      },    },  },}

  از این تنظیم فقط جایی استفاده کنید که هر نوبت عادی باید ابزاری را فراخوانی کند. local/my-local-model را با ارجاع دقیق از openclaw models list جایگزین کنید، یا آن را از طریق CLI تنظیم کنید:

  openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge

• سطوح بیشتر تلاش استدلال: اگر یک مدل سفارشی سازگار با OpenAI سطوح تلاش استدلال OpenAI فراتر از پروفایل داخلی را می‌پذیرد، آن‌ها را در بلوک سازگاری مدل اعلام کنید. افزودن "xhigh" آن را برای ارجاع آن مدل در /think xhigh، انتخابگرهای نشست، اعتبارسنجی Gateway و اعتبارسنجی llm-task در دسترس قرار می‌دهد:

  {  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "sk-local",        api: "openai-responses",        models: [          {            id: "gpt-5.4",            name: "GPT 5.4 از طریق پراکسی محلی",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 196608,            maxTokens: 8192,            compat: {              supportedReasoningEfforts: ["low", "medium", "high", "xhigh"],              reasoningEffortMap: { xhigh: "xhigh" },            },          },        ],      },    },  },}

بک‌اندهای کوچک‌تر یا سخت‌گیرانه‌تر

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

1. پاسخ‌دادن مدل محلی را تأیید کنید - بدون ابزار و بدون زمینهٔ عامل:

   openclaw infer model run --local --model <provider/model> --prompt "دقیقاً با این متن پاسخ بده: pong" --json

2. مسیریابی Gateway را تأیید کنید - فقط پرامپت را ارسال می‌کند و از رونوشت، راه‌اندازی اولیهٔ AGENTS، سرهم‌بندی موتور زمینه، ابزارها و سرورهای MCP همراه صرف‌نظر می‌کند، اما همچنان مسیریابی Gateway، احراز هویت و انتخاب ارائه‌دهنده را می‌آزماید:

   openclaw infer model run --gateway --model <provider/model> --prompt "دقیقاً با این متن پاسخ بده: pong" --json

3. اگر هر دو کاوش موفق‌اند، اما اجرای واقعی عامل به‌دلیل فراخوانی‌های ابزار بدشکل یا پرامپت‌های بیش‌ازحد بزرگ شکست می‌خورد، حالت سبک را امتحان کنید: مقدار agents.defaults.experimental.localModelLean: true را تنظیم کنید. این حالت ابزارهای سنگین مرورگر، Cron، پیام، تولید رسانه، صدا و PDF را حذف می‌کند، مگر اینکه صراحتاً لازم باشند، و فهرست‌های بزرگ‌تر ابزار را به‌طور پیش‌فرض پشت کنترل‌های ساختاریافتهٔ جست‌وجوی ابزار قرار می‌دهد، درحالی‌که exec را مستقیماً قابل‌مشاهده نگه می‌دارد. برای جزئیات و روش تأیید فعال‌بودن آن، به ویژگی‌های آزمایشی -> حالت سبک مدل محلی مراجعه کنید.

4. به‌عنوان آخرین راه‌حل، با تنظیم models.providers.<provider>.models[].compat.supportsTools: false برای آن مدل، ابزارها را کاملاً غیرفعال کنید - سپس عامل بدون فراخوانی ابزار اجرا می‌شود.

5. پس از آن، گلوگاه در بالادست است. اگر بک‌اند پس از فعال‌کردن حالت سبک و supportsTools: false همچنان فقط در اجراهای بزرگ‌تر OpenClaw شکست می‌خورد، مشکل باقی‌مانده معمولاً از خود مدل یا سرور است - پنجرهٔ زمینه، حافظهٔ GPU، تخلیهٔ kv-cache یا یک اشکال در بک‌اند - نه لایهٔ انتقال OpenClaw.

عیب‌یابی

• Gateway نمی‌تواند به پراکسی دسترسی پیدا کند؟ curl http://127.0.0.1:1234/v1/models.
• مدل LM Studio بارگذاری نشده است؟ آن را دوباره بارگذاری کنید؛ شروع سرد یکی از دلایل رایج «گیرکردن» است.
• سرور محلی terminated، ECONNRESET را گزارش می‌کند یا جریان را در میانهٔ اجرا می‌بندد؟ OpenClaw یک model.call.error.failureKind با کاردینالیتی پایین را به‌همراه تصویر لحظه‌ای RSS/heap فرایند OpenClaw در اطلاعات تشخیصی ثبت می‌کند. برای فشار حافظهٔ LM Studio/Ollama، آن مُهر زمانی را با گزارش سرور یا گزارش خرابی/jetsam در macOS تطبیق دهید تا مشخص شود آیا سرور مدل متوقف شده است یا خیر.
• خطاهای زمینه رخ می‌دهد؟ OpenClaw آستانه‌های بررسی اولیهٔ پنجرهٔ زمینه را از پنجرهٔ شناسایی‌شدهٔ مدل (یا پنجرهٔ محدودشده، وقتی agents.defaults.contextTokens آن را کاهش می‌دهد) استخراج می‌کند؛ در کمتر از 20% با حداقل 8k هشدار می‌دهد و در کمتر از 10% با حداقل 4k اجرای آن را کاملاً مسدود می‌کند (این مقدار به پنجرهٔ زمینهٔ مؤثر محدود می‌شود تا فرادادهٔ بیش‌ازحد بزرگ مدل نتواند محدودیت معتبر کاربر را رد کند). contextWindow را کاهش دهید یا محدودیت زمینهٔ سرور/مدل را افزایش دهید.
• messages[].content ... expected a string؟ compat.requiresStringContent: true را به ورودی آن مدل اضافه کنید.
• validation.keys، یا «ورودی‌های پیام فقط role و content را مجاز می‌دانند»؟ compat.strictMessageKeys: true را به ورودی آن مدل اضافه کنید.
• فراخوانی‌های مستقیم /v1/chat/completions کار می‌کنند، اما openclaw infer model run --local در Gemma یا مدل محلی دیگری شکست می‌خورد؟ ابتدا URL ارائه‌دهنده، ارجاع مدل، نشانگر احراز هویت و گزارش‌های سرور را بررسی کنید - model run ابزارهای عامل را کاملاً نادیده می‌گیرد. اگر model run موفق است، اما اجرای بزرگ‌تر عامل شکست می‌خورد، سطح ابزار را با localModelLean یا compat.supportsTools: false کاهش دهید.
• فراخوانی‌های ابزار به‌شکل متن خام JSON/XML/ReAct ظاهر می‌شوند، یا ارائه‌دهنده یک آرایهٔ خالی tool_calls برمی‌گرداند؟ پراکسی‌ای اضافه نکنید که کورکورانه متن دستیار را به اجرای ابزار تبدیل کند - ابتدا الگو/تجزیه‌گر گفت‌وگوی سرور را اصلاح کنید. اگر مدل فقط زمانی کار می‌کند که استفاده از ابزار اجباری باشد، بازنویسی params.extra_body.tool_choice: "required" در بالا را اضافه کنید و از آن ورودی مدل فقط برای نشست‌هایی استفاده کنید که در هر نوبت انتظار فراخوانی ابزار می‌رود.
• ایمنی: مدل‌های محلی از فیلترهای سمت ارائه‌دهنده صرف‌نظر می‌کنند. عامل‌ها را محدود نگه دارید و Compaction را فعال کنید تا شعاع اثر تزریق پرامپت محدود شود.

مرتبط

• مرجع پیکربندی
• جایگزینی مدل هنگام خرابی