مدل‌های محلی

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

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

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

برای یک چرخهٔ عامل روان، ۲ یا چند Mac Studio با بالاترین پیکربندی یا یک سامانهٔ GPU هم‌تراز (حدود ۳۰ هزار دلار یا بیشتر) را هدف بگیرید. یک GPU با حافظهٔ ۲۴ گیگابایت فقط پرامپت‌های سبک‌تر را با تأخیر بیشتر مدیریت می‌کند. همیشه بزرگ‌ترین گونه یا گونهٔ کامل قابل میزبانی را اجرا کنید؛ نقاط وارسی کوچک یا با کوانتیزه‌سازی شدید، خطر تزریق پرامپت را افزایش می‌دهند (به امنیت مراجعه کنید).

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

وقتی بک‌اند از آن پشتیبانی می‌کند، از api: "openai-responses" استفاده کنید (LM Studio پشتیبانی می‌کند). در غیر این صورت از api: "openai-completions" استفاده کنید. اگر در یک ارائه‌دهندهٔ سفارشی دارای baseUrl، مقدار api حذف شود، مقدار پیش‌فرض 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 سفارشی، در صورتی کار می‌کند که یک نقطهٔ پایانی /v1/chat/completions به سبک OpenAI ارائه دهد. مگر اینکه بک‌اند صراحتاً پشتیبانی از /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 پیکربندی‌شدهٔ خود را برای درخواست‌های محافظت‌شدهٔ مدل قابل‌اعتماد می‌دانند؛ این شامل میزبان‌های local loopback، شبکهٔ محلی، 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، بدون store در Responses، بدون شکل‌دهی محمولهٔ سازگاری استدلال 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 via local proxy",            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 "Reply with exactly: pong" --json

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

   openclaw infer model run --gateway --model <provider/model> --prompt "Reply with exactly: 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 آن را کاهش می‌دهد، از پنجرهٔ سقف‌گذاری‌شده)؛ زیر ۲۰٪ با حداقل 8k هشدار می‌دهد و زیر ۱۰٪ با حداقل 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 را فعال کنید تا دامنهٔ اثر تزریق پرامپت محدود شود.

مرتبط

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