Providers
Ollama
OpenClaw با API بومی Ollama (/api/chat) برای مدلهای ابری میزبانیشده و سرورهای محلی/خودمیزبان Ollama یکپارچه میشود. میتوانید از Ollama در سه حالت استفاده کنید: Cloud + Local از طریق یک میزبان Ollama قابل دسترس، Cloud only در برابر https://ollama.com، یا Local only در برابر یک میزبان Ollama قابل دسترس.
OpenClaw همچنین ollama-cloud را بهعنوان شناسه ارائهدهنده میزبانیشده درجهاول برای
استفاده مستقیم از Ollama Cloud ثبت میکند. وقتی مسیریابی فقط ابری میخواهید
بدون اینکه شناسه ارائهدهنده محلی ollama را به اشتراک بگذارید، از ارجاعهایی مانند ollama-cloud/kimi-k2.5:cloud استفاده کنید.
برای صفحه راهاندازی اختصاصی فقط ابری، Ollama Cloud را ببینید.
پیکربندی ارائهدهنده Ollama از baseUrl بهعنوان کلید معیار استفاده میکند. OpenClaw برای سازگاری با نمونههای سبک OpenAI SDK، baseURL را نیز میپذیرد، اما پیکربندی جدید باید baseUrl را ترجیح دهد.
قواعد احراز هویت
Local and LAN hosts
میزبانهای محلی و LAN مربوط به Ollama به توکن bearer واقعی نیاز ندارند. OpenClaw نشانگر محلی ollama-local را فقط برای loopback، شبکه خصوصی، .local، و URLهای پایه Ollama با نام میزبان ساده استفاده میکند.
Remote and Ollama Cloud hosts
میزبانهای عمومی راه دور و Ollama Cloud (https://ollama.com) از طریق OLLAMA_API_KEY، یک نمایه احراز هویت، یا apiKey ارائهدهنده به یک اعتبارنامه واقعی نیاز دارند. برای استفاده میزبانیشده مستقیم، ارائهدهنده ollama-cloud را ترجیح دهید.
Custom provider ids
شناسههای ارائهدهنده سفارشی که api: "ollama" را تنظیم میکنند، از همان قواعد پیروی میکنند. برای نمونه، یک ارائهدهنده ollama-remote که به یک میزبان Ollama در LAN خصوصی اشاره میکند، میتواند از apiKey: "ollama-local" استفاده کند و زیرفرستادهها آن نشانگر را از طریق هوک ارائهدهنده Ollama حل میکنند، بهجای اینکه آن را اعتبارنامه گمشده تلقی کنند. جستوجوی حافظه نیز میتواند agents.defaults.memorySearch.provider را روی آن شناسه ارائهدهنده سفارشی تنظیم کند تا embeddingها از نقطه پایانی Ollama متناظر استفاده کنند.
Auth profiles
auth-profiles.json اعتبارنامه را برای یک شناسه ارائهدهنده ذخیره میکند. تنظیمات نقطه پایانی (baseUrl، api، شناسههای مدل، سرآیندها، زمانانتظارها) را در models.providers.<id> قرار دهید. فایلهای قدیمی نمایه احراز هویت تخت مانند { "ollama-windows": { "apiKey": "ollama-local" } } قالب زمان اجرا نیستند؛ openclaw doctor --fix را اجرا کنید تا آنها با تهیه نسخه پشتیبان، به نمایه کلید API معیار ollama-windows:default بازنویسی شوند. baseUrl در آن فایل نویز سازگاری است و باید به پیکربندی ارائهدهنده منتقل شود.
Memory embedding scope
وقتی Ollama برای embeddingهای حافظه استفاده میشود، احراز هویت bearer به میزبانی محدود میشود که در آن اعلام شده است:
- یک کلید در سطح ارائهدهنده فقط به میزبان Ollama همان ارائهدهنده ارسال میشود.
agents.*.memorySearch.remote.apiKeyفقط به میزبان embedding راه دور خودش ارسال میشود.- مقدار env خالص
OLLAMA_API_KEYبهعنوان قرارداد Ollama Cloud در نظر گرفته میشود و بهطور پیشفرض به میزبانهای محلی یا خودمیزبان ارسال نمیشود.
شروع به کار
روش و حالت راهاندازی موردنظر خود را انتخاب کنید.
Onboarding (recommended)
بهترین برای: سریعترین مسیر به یک راهاندازی ابری یا محلی کارآمد Ollama.
Run onboarding
openclaw onboardاز فهرست ارائهدهندهها Ollama را انتخاب کنید.
Choose your mode
- ابری + محلی — میزبان محلی Ollama بههمراه مدلهای ابری که از طریق آن میزبان مسیریابی میشوند
- فقط ابری — مدلهای میزبانیشده Ollama از طریق
https://ollama.com - فقط محلی — فقط مدلهای محلی
Select a model
Cloud only برای OLLAMA_API_KEY درخواست میدهد و پیشفرضهای ابری میزبانیشده را پیشنهاد میکند. Cloud + Local و Local only یک URL پایه Ollama میخواهند، مدلهای موجود را کشف میکنند، و اگر مدل محلی انتخابشده هنوز موجود نباشد آن را بهصورت خودکار pull میکنند. وقتی Ollama یک برچسب نصبشده :latest مانند gemma4:latest گزارش میکند، راهاندازی آن مدل نصبشده را یکبار نشان میدهد، بهجای اینکه هم gemma4 و هم gemma4:latest را نشان دهد یا alias ساده را دوباره pull کند. Cloud + Local همچنین بررسی میکند آیا آن میزبان Ollama برای دسترسی ابری وارد حساب شده است یا نه.
Verify the model is available
openclaw models list --provider ollamaحالت غیرتعاملی
openclaw onboard --non-interactive \ --auth-choice ollama \ --accept-riskدر صورت تمایل یک URL پایه یا مدل سفارشی مشخص کنید:
openclaw onboard --non-interactive \ --auth-choice ollama \ --custom-base-url "http://ollama-host:11434" \ --custom-model-id "qwen3.5:27b" \ --accept-riskManual setup
بهترین برای: کنترل کامل روی راهاندازی ابری یا محلی.
Choose cloud or local
- ابری + محلی: Ollama را نصب کنید، با
ollama signinوارد شوید، و درخواستهای ابری را از طریق آن میزبان مسیریابی کنید - فقط ابری: از
https://ollama.comبا یکOLLAMA_API_KEYاستفاده کنید - فقط محلی: Ollama را از ollama.com/download نصب کنید
Pull a local model (local only)
ollama pull gemma4# orollama pull gpt-oss:20b# orollama pull llama3.3Enable Ollama for OpenClaw
برای Cloud only از OLLAMA_API_KEY واقعی خود استفاده کنید. برای راهاندازیهای متکی به میزبان، هر مقدار placeholder کار میکند:
# Cloudexport OLLAMA_API_KEY="your-ollama-api-key" # Local-onlyexport OLLAMA_API_KEY="ollama-local" # Or configure in your config fileopenclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"Inspect and set your model
openclaw models listopenclaw models set ollama/gemma4یا پیشفرض را در پیکربندی تنظیم کنید:
{ agents: { defaults: { model: { primary: "ollama/gemma4" }, }, },}مدلهای ابری
Cloud + Local
Cloud + Local از یک میزبان Ollama قابل دسترس بهعنوان نقطه کنترل برای مدلهای محلی و ابری استفاده میکند. این جریان ترکیبی ترجیحی Ollama است.
در هنگام راهاندازی از ابری + محلی استفاده کنید. OpenClaw برای URL پایه Ollama درخواست میدهد، مدلهای محلی را از آن میزبان کشف میکند، و بررسی میکند آیا میزبان با ollama signin برای دسترسی ابری وارد حساب شده است یا نه. وقتی میزبان وارد حساب شده باشد، OpenClaw همچنین پیشفرضهای ابری میزبانیشده مانند kimi-k2.5:cloud، minimax-m2.7:cloud، و glm-5.1:cloud را پیشنهاد میکند.
اگر میزبان هنوز وارد حساب نشده باشد، OpenClaw راهاندازی را تا زمانی که ollama signin را اجرا کنید فقط محلی نگه میدارد.
Cloud only
Cloud only در برابر API میزبانیشده Ollama در https://ollama.com اجرا میشود.
در هنگام راهاندازی از فقط ابری استفاده کنید. OpenClaw برای OLLAMA_API_KEY درخواست میدهد، baseUrl: "https://ollama.com" را تنظیم میکند، و فهرست مدلهای ابری میزبانیشده را seed میکند. این مسیر به سرور محلی Ollama یا ollama signin نیاز ندارد.
فهرست مدلهای ابری که هنگام openclaw onboard نشان داده میشود، بهصورت زنده از https://ollama.com/api/tags پر میشود و به ۵۰۰ ورودی محدود است؛ بنابراین انتخابگر بهجای یک seed ایستا، کاتالوگ میزبانیشده فعلی را بازتاب میدهد. اگر ollama.com در زمان راهاندازی در دسترس نباشد یا هیچ مدلی برنگرداند، OpenClaw به پیشنهادهای hardcoded قبلی برمیگردد تا onboarding همچنان کامل شود.
همچنین میتوانید ارائهدهنده ابری درجهاول را مستقیم پیکربندی کنید:
openclaw onboard --auth-choice ollama-cloudopenclaw models set ollama-cloud/kimi-k2.5:cloudLocal only
در حالت فقط محلی، OpenClaw مدلها را از نمونه پیکربندیشده Ollama کشف میکند. این مسیر برای سرورهای محلی یا خودمیزبان Ollama است.
OpenClaw در حال حاضر gemma4 را بهعنوان پیشفرض محلی پیشنهاد میکند.
کشف مدل (ارائهدهنده ضمنی)
وقتی OLLAMA_API_KEY (یا یک نمایه احراز هویت) را تنظیم میکنید و models.providers.ollama یا ارائهدهنده راه دور سفارشی دیگری با api: "ollama" تعریف نمیکنید، OpenClaw مدلها را از نمونه محلی Ollama در http://127.0.0.1:11434 کشف میکند.
| رفتار | جزئیات |
|---|---|
| پرسوجوی کاتالوگ | از /api/tags پرسوجو میکند |
| تشخیص قابلیت | از lookupهای best-effort مربوط به /api/show برای خواندن contextWindow، پارامترهای Modelfile گسترشیافته num_ctx، و قابلیتهایی از جمله vision/tools استفاده میکند |
| مدلهای بینایی | مدلهایی با قابلیت vision گزارششده توسط /api/show بهعنوان دارای قابلیت تصویر علامتگذاری میشوند (input: ["text", "image"])، بنابراین OpenClaw تصاویر را بهصورت خودکار در prompt تزریق میکند |
| تشخیص استدلال | وقتی موجود باشد از قابلیتهای /api/show، از جمله thinking، استفاده میکند؛ وقتی Ollama قابلیتها را حذف کند، به یک heuristic مبتنی بر نام مدل (r1، reasoning، think) برمیگردد |
| محدودیتهای توکن | maxTokens را روی سقف پیشفرض حداکثر توکن Ollama که OpenClaw استفاده میکند تنظیم میکند |
| هزینهها | همه هزینهها را روی 0 تنظیم میکند |
این کار از ورودیهای دستی مدل جلوگیری میکند، درحالیکه کاتالوگ را با نمونه محلی Ollama همسو نگه میدارد. میتوانید در infer model run محلی از یک ارجاع کامل مانند ollama/<pulled-model>:latest استفاده کنید؛ OpenClaw آن مدل نصبشده را از کاتالوگ زنده Ollama حل میکند، بدون اینکه به ورودی دستی models.json نیاز داشته باشد.
برای میزبانهای Ollama واردشده به حساب، برخی مدلهای :cloud ممکن است از طریق /api/chat
و /api/show قابل استفاده باشند، پیش از آنکه در /api/tags ظاهر شوند. وقتی بهصراحت یک
ارجاع کامل ollama/<model>:cloud را انتخاب میکنید، OpenClaw همان مدل گمشده دقیق را با
/api/show اعتبارسنجی میکند و فقط اگر Ollama فراداده مدل را تأیید کند، آن را به کاتالوگ زمان اجرا
اضافه میکند. خطاهای تایپی همچنان بهعنوان مدلهای ناشناخته شکست میخورند، نه اینکه بهصورت خودکار ساخته شوند.
# See what models are availableollama listopenclaw models listبرای یک smoke test محدود تولید متن که از سطح کامل ابزار فرستاده پرهیز میکند،
از infer model run محلی با یک ارجاع کامل مدل Ollama استفاده کنید:
OLLAMA_API_KEY=ollama-local \ openclaw infer model run \ --local \ --model ollama/llama3.2:latest \ --prompt "Reply with exactly: pong" \ --jsonآن مسیر همچنان از ارائهدهنده، احراز هویت، و انتقال بومی Ollama پیکربندیشده OpenClaw استفاده میکند، اما یک نوبت chat-agent را شروع نمیکند یا زمینه MCP/ابزار را بارگذاری نمیکند. اگر این موفق شود اما پاسخهای عادی فرستاده شکست بخورند، در گام بعد ظرفیت prompt/ابزار فرستاده مدل را عیبیابی کنید.
برای یک smoke test محدود مدل بینایی روی همان مسیر سبک، یک یا چند
فایل تصویر به infer model run اضافه کنید. این کار prompt و تصویر را مستقیم به
مدل بینایی Ollama انتخابشده میفرستد، بدون اینکه ابزارهای چت، حافظه، یا زمینه
جلسه قبلی را بارگذاری کند:
OLLAMA_API_KEY=ollama-local \ openclaw infer model run \ --local \ --model ollama/qwen2.5vl:7b \ --prompt "Describe this image in one sentence." \ --file ./photo.jpg \ --jsonmodel run --file فایلهایی را که بهصورت image/* شناسایی میشوند، از جمله ورودیهای رایج PNG،
JPEG، و WebP میپذیرد. فایلهای غیرتصویری پیش از فراخوانی Ollama رد میشوند.
برای تشخیص گفتار، بهجای آن از openclaw infer audio transcribe استفاده کنید.
وقتی یک گفتوگو را با /model ollama/<model> تغییر میدهید، OpenClaw آن را
بهعنوان انتخاب دقیق کاربر در نظر میگیرد. اگر baseUrl پیکربندیشده Ollama
در دسترس نباشد، پاسخ بعدی با خطای ارائهدهنده شکست میخورد، بهجای اینکه بیصدا
از یک مدل fallback پیکربندیشده دیگر پاسخ دهد.
کارهای cron ایزوله پیش از شروع نوبت agent یک بررسی ایمنی محلی اضافی انجام میدهند.
اگر مدل انتخابشده به یک ارائهدهنده Ollama محلی، شبکه خصوصی، یا .local
resolve شود و /api/tags در دسترس نباشد، OpenClaw آن اجرای cron را با وضعیت
skipped و همراه با ollama/<model> انتخابشده در متن خطا ثبت میکند. پیشبررسی
endpoint بهمدت ۵ دقیقه cache میشود، بنابراین چندین کار cron که به همان daemon
متوقفشده Ollama اشاره میکنند همگی درخواستهای مدل ناموفق را اجرا نمیکنند.
مسیر متن محلی، مسیر stream بومی، و embeddings را در برابر Ollama محلی بهصورت زنده تأیید کنید با:
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \ pnpm test:live -- extensions/ollama/ollama.live.test.tsبرای smoke testهای کلید API در Ollama Cloud، آزمون زنده را به https://ollama.com
اشاره دهید و یک مدل hosted از کاتالوگ فعلی انتخاب کنید:
export OLLAMA_API_KEY='<your-ollama-cloud-api-key>' OPENCLAW_LIVE_TEST=1 \OPENCLAW_LIVE_OLLAMA=1 \OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \OPENCLAW_LIVE_OLLAMA_MODEL=glm-5.1:cloud \OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=1 \pnpm test:live -- extensions/ollama/ollama.live.test.tssmoke ابری متن، stream بومی، و جستوجوی وب را اجرا میکند. بهصورت پیشفرض برای
https://ollama.com از embeddings صرفنظر میکند، چون کلیدهای API در Ollama Cloud ممکن است
مجوز استفاده از /api/embed را نداشته باشند. وقتی صریحاً میخواهید آزمون زنده
در صورت ناتوانی کلید ابری پیکربندیشده از استفاده از endpoint embed شکست بخورد،
OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1 را تنظیم کنید.
برای افزودن یک مدل جدید، کافی است آن را با Ollama pull کنید:
ollama pull mistralمدل جدید بهصورت خودکار کشف میشود و برای استفاده در دسترس خواهد بود.
استنتاج محلی در Node
Agentها میتوانند یک کار کوتاه را به یک مدل Ollama نصبشده روی یک desktop یا server node
جفتشده واگذار کنند. prompt و پاسخ از اتصال احراز هویتشده موجود Gateway/node عبور میکنند؛
درخواست مدل روی node انتخابشده و در برابر endpoint استاندارد loopback آن برای Ollama
(http://127.0.0.1:11434) اجرا میشود.
Ollama را روی node شروع کنید
دستکم یک مدل chat را pull کنید و Ollama را در حال اجرا نگه دارید:
ollama pull qwen3:0.6bollama listمیزبان node را متصل کنید
روی همان ماشینی که Ollama اجرا میشود، یک میزبان node را به Gateway متصل کنید:
openclaw node run \ --host <gateway-host> \ --port 18789 \ --display-name "Local inference"دستگاه جدید و فرمانهای node اعلامشده آن را روی میزبان Gateway تأیید کنید، سپس node را بررسی کنید:
openclaw devices listopenclaw devices approve <deviceRequestId>openclaw nodes pendingopenclaw nodes approve <nodeRequestId>openclaw nodes status --connectedهم اتصال نخست و هم ارتقایی که فرمانهای Ollama را اضافه میکند میتوانند
تأیید فرمان node را trigger کنند. اگر node بدون اعلام
ollama.models و ollama.chat متصل شد، دوباره openclaw nodes pending را بررسی کنید.
از یک agent بخواهید از استنتاج محلی استفاده کند
Plugin همراه Ollama ابزار node_inference را ارائه میکند. Agentها ابتدا
از action: "discover" استفاده میکنند، سپس با یک node و مدل بازگرداندهشده
از action: "run" استفاده میکنند. اگر دقیقاً یک node توانمند متصل باشد، run میتواند node را حذف کند.
برای مثال: «مدلهای Ollama روی nodeهای من را کشف کن، سپس از سریعترین مدل بارگذاریشده برای خلاصه کردن این متن استفاده کن.»
کشف، /api/tags را میخواند، قابلیتهای /api/show را بررسی میکند، و در صورت
دسترس بودن از /api/ps استفاده میکند تا مدلهای ازپیشبارگذاریشده را اولویت دهد.
فقط مدلهای chat-capable محلی را برمیگرداند: ردیفهای Ollama Cloud و مدلهای فقط embedding
حذف میشوند. هر اجرا از Ollama میخواهد thinking مدل را غیرفعال کند و خروجی را به ۵۱۲ token
محدود میکند، مگر اینکه فراخوانی ابزار مقدار متفاوتی برای maxTokens درخواست کند. برخی مدلها،
مانند GPT-OSS، از غیرفعال کردن thinking پشتیبانی نمیکنند و ممکن است همچنان از reasoning tokens استفاده کنند.
برای اینکه Ollama روی یک node در حال اجرا بماند بدون اینکه برای agentها در دسترس باشد، مورد زیر را در config مورد استفاده آن میزبان node تنظیم کنید:
openclaw config set plugins.entries.ollama.config.nodeInference.enabled falseاگر node از فرمان foreground openclaw node run در setup بالا استفاده میکند،
آن فرایند را متوقف کنید و فرمان را دوباره اجرا کنید. اگر از یک سرویس node نصبشده استفاده میکند،
openclaw node restart را اجرا کنید.
node دیگر ollama.models و ollama.chat را اعلام نمیکند؛ خود Ollama و
ارائهدهنده Ollama در Gateway بدون تغییر میمانند. مقدار را به true تنظیم کنید و
node را restart کنید تا استنتاج محلی دوباره اعلام شود. سطح فرمان تغییرکرده
ممکن است پس از اتصال دوباره نیاز به تأیید از طریق openclaw nodes pending داشته باشد.
میتوانید همان فرمانهای node را بدون نوبت agent بررسی کنید:
openclaw nodes invoke \ --node "Local inference" \ --command ollama.models \ --params '{}' \ --invoke-timeout 90000 \ --timeout 100000 openclaw nodes invoke \ --node "Local inference" \ --command ollama.chat \ --params '{"model":"qwen3:0.6b","prompt":"Reply with exactly: pong","maxTokens":32,"timeoutMs":120000}' \ --invoke-timeout 130000 \ --timeout 140000استنتاج محلی در Node عمداً از models.providers.ollama.baseUrl remote یا ابری
دوباره استفاده نمیکند. Ollama را روی endpoint استاندارد loopback node شروع کنید.
فرمانهای node بهصورت پیشفرض روی میزبانهای node در macOS، Linux، و
Windows در دسترس هستند و همچنان مشمول سیاست عادی جفتسازی node و فرمان میمانند.
بینایی و توضیح تصویر
Plugin همراه Ollama، Ollama را بهعنوان یک ارائهدهنده درک رسانه با قابلیت تصویر ثبت میکند. این امکان را به OpenClaw میدهد که درخواستهای صریح توضیح تصویر و پیشفرضهای image-model پیکربندیشده را از طریق مدلهای vision محلی یا hosted در Ollama مسیریابی کند.
برای vision محلی، مدلی را pull کنید که از تصویر پشتیبانی میکند:
ollama pull qwen2.5vl:7bexport OLLAMA_API_KEY="ollama-local"سپس با infer CLI تأیید کنید:
openclaw infer image describe \ --file ./photo.jpg \ --model ollama/qwen2.5vl:7b \ --json--model باید یک ref کامل <provider/model> باشد. وقتی تنظیم شده باشد، openclaw infer image describe ابتدا آن مدل را امتحان میکند، بهجای اینکه بهدلیل پشتیبانی مدل از vision بومی از توضیح صرفنظر کند. اگر فراخوانی مدل شکست بخورد، OpenClaw میتواند از طریق agents.defaults.imageModel.fallbacks پیکربندیشده ادامه دهد؛ خطاهای آمادهسازی فایل یا URL همچنان پیش از تلاشهای fallback شکست میخورند.
وقتی جریان ارائهدهنده درک تصویر OpenClaw، agents.defaults.imageModel پیکربندیشده، و شکل خروجی توضیح تصویر را میخواهید، از infer image describe استفاده کنید. وقتی یک probe خام مدل چندوجهی با prompt سفارشی و یک یا چند تصویر میخواهید، از infer model run --file استفاده کنید.
برای اینکه Ollama مدل پیشفرض درک تصویر برای رسانه ورودی باشد، agents.defaults.imageModel را پیکربندی کنید:
{ agents: { defaults: { imageModel: { primary: "ollama/qwen2.5vl:7b", }, }, },}ref کامل ollama/<model> را ترجیح دهید. اگر همان مدل زیر models.providers.ollama.models با input: ["text", "image"] فهرست شده باشد و هیچ ارائهدهنده تصویر پیکربندیشده دیگری آن شناسه مدل bare را ارائه نکند، OpenClaw یک ref bare در imageModel مانند qwen2.5vl:7b را نیز به ollama/qwen2.5vl:7b normalize میکند. اگر بیش از یک ارائهدهنده تصویر پیکربندیشده همان bare ID را داشته باشد، پیشوند ارائهدهنده را صریحاً استفاده کنید.
مدلهای vision محلی کند ممکن است به timeout طولانیتری برای درک تصویر نسبت به مدلهای ابری نیاز داشته باشند. همچنین ممکن است وقتی Ollama تلاش میکند context کامل vision اعلامشده را روی سختافزار محدود تخصیص دهد crash کنند یا متوقف شوند. یک capability timeout تنظیم کنید و وقتی فقط یک نوبت عادی توضیح تصویر نیاز دارید، num_ctx را روی entry مدل محدود کنید:
{ models: { providers: { ollama: { models: [ { id: "qwen2.5vl:7b", name: "qwen2.5vl:7b", input: ["text", "image"], params: { num_ctx: 2048, keep_alive: "1m" }, }, ], }, }, }, tools: { media: { image: { timeoutSeconds: 180, models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }], }, }, },}این timeout برای درک تصویر ورودی و ابزار صریح image که agent میتواند در طول یک نوبت فراخوانی کند اعمال میشود. models.providers.ollama.timeoutSeconds در سطح ارائهدهنده همچنان guard درخواست HTTP زیرین Ollama را برای فراخوانیهای عادی مدل کنترل میکند.
ابزار تصویر صریح را در برابر Ollama محلی بهصورت زنده تأیید کنید با:
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \ pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.tsاگر models.providers.ollama.models را دستی تعریف میکنید، مدلهای vision را با پشتیبانی ورودی تصویر علامتگذاری کنید:
{ id: "qwen2.5vl:7b", name: "qwen2.5vl:7b", input: ["text", "image"], contextWindow: 128000, maxTokens: 8192,}OpenClaw درخواستهای توضیح تصویر را برای مدلهایی که image-capable علامتگذاری نشدهاند رد میکند. با کشف ضمنی، OpenClaw این را زمانی از Ollama میخواند که /api/show قابلیت vision را گزارش کند.
پیکربندی
پایه (کشف ضمنی)
سادهترین مسیر فعالسازی فقط محلی از طریق متغیر محیطی است:
export OLLAMA_API_KEY="ollama-local"صریح (مدلهای دستی)
وقتی setup ابری hosted میخواهید، Ollama روی host/port دیگری اجرا میشود، میخواهید context windowها یا فهرست مدلهای خاصی را اجبار کنید، یا تعریف مدلهای کاملاً دستی میخواهید، از config صریح استفاده کنید.
{ models: { providers: { ollama: { baseUrl: "https://ollama.com", apiKey: "OLLAMA_API_KEY", api: "ollama", models: [ { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", reasoning: false, input: ["text", "image"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, maxTokens: 8192 } ] } } }}URL پایه سفارشی
اگر Ollama روی host یا port متفاوتی اجرا میشود (config صریح کشف خودکار را غیرفعال میکند، بنابراین مدلها را دستی تعریف کنید):
{ models: { providers: { ollama: { apiKey: "ollama-local", baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL api: "ollama", // Set explicitly to guarantee native tool-calling behavior timeoutSeconds: 300, // Optional: give cold local models longer to connect and stream models: [ { id: "qwen3:32b", name: "qwen3:32b", params: { keep_alive: "15m", // Optional: keep the model loaded between turns }, }, ], }, }, },}دستورکارهای رایج
از اینها بهعنوان نقطه شروع استفاده کنید و شناسههای مدل را با نامهای دقیق خروجی ollama list یا openclaw models list --provider ollama جایگزین کنید.
مدل محلی با کشف خودکار
زمانی از این استفاده کنید که Ollama روی همان ماشینی اجرا میشود که Gateway روی آن است و میخواهید OpenClaw مدلهای نصبشده را بهطور خودکار کشف کند.
ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4این مسیر پیکربندی را حداقلی نگه میدارد. مگر اینکه بخواهید مدلها را دستی تعریف کنید، بلوک models.providers.ollama اضافه نکنید.
میزبان Ollama روی LAN با مدلهای دستی
برای میزبانهای LAN از URLهای بومی Ollama استفاده کنید. /v1 اضافه نکنید.
{ models: { providers: { ollama: { baseUrl: "http://gpu-box.local:11434", apiKey: "ollama-local", api: "ollama", timeoutSeconds: 300, contextWindow: 32768, maxTokens: 8192, models: [ { id: "qwen3.5:9b", name: "qwen3.5:9b", reasoning: true, input: ["text"], params: { num_ctx: 32768, thinking: false, keep_alive: "15m", }, }, ], }, }, }, agents: { defaults: { model: { primary: "ollama/qwen3.5:9b" }, }, },}contextWindow بودجه زمینه در سمت OpenClaw است. params.num_ctx برای درخواست به Ollama فرستاده میشود. وقتی سختافزار شما نمیتواند زمینه کامل اعلامشده مدل را اجرا کند، این دو را همراستا نگه دارید.
فقط Ollama Cloud
وقتی daemon محلی اجرا نمیکنید و مدلهای میزبانیشده Ollama را مستقیماً میخواهید، از این استفاده کنید.
export OLLAMA_API_KEY="your-ollama-api-key"{ models: { providers: { ollama: { baseUrl: "https://ollama.com", apiKey: "OLLAMA_API_KEY", api: "ollama", models: [ { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", reasoning: false, input: ["text", "image"], contextWindow: 128000, maxTokens: 8192, }, ], }, }, }, agents: { defaults: { model: { primary: "ollama/kimi-k2.5:cloud" }, }, },}ابر بههمراه محلی از طریق daemon واردشده
وقتی یک daemon محلی یا LAN مربوط به Ollama با ollama signin وارد شده است و باید هم مدلهای محلی و هم مدلهای :cloud را سرو کند، از این استفاده کنید.
ollama signinollama pull gemma4{ models: { providers: { ollama: { baseUrl: "http://127.0.0.1:11434", apiKey: "ollama-local", api: "ollama", timeoutSeconds: 300, models: [ { id: "gemma4", name: "gemma4", input: ["text"] }, { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] }, ], }, }, }, agents: { defaults: { model: { primary: "ollama/gemma4", fallbacks: ["ollama/kimi-k2.5:cloud"], }, }, },}چند میزبان Ollama
وقتی بیش از یک سرور Ollama دارید، از شناسههای provider سفارشی استفاده کنید. هر provider میزبان، مدلها، احراز هویت، timeout و ارجاعهای مدل خودش را دارد.
{ models: { providers: { "ollama-fast": { baseUrl: "http://mini.local:11434", apiKey: "ollama-local", api: "ollama", contextWindow: 32768, models: [{ id: "gemma4", name: "gemma4", input: ["text"] }], }, "ollama-large": { baseUrl: "http://gpu-box.local:11434", apiKey: "ollama-local", api: "ollama", timeoutSeconds: 420, contextWindow: 131072, maxTokens: 16384, models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }], }, }, }, agents: { defaults: { model: { primary: "ollama-fast/gemma4", fallbacks: ["ollama-large/qwen3.5:27b"], }, }, },}وقتی OpenClaw درخواست را میفرستد، پیشوند provider فعال حذف میشود تا ollama-large/qwen3.5:27b بهشکل qwen3.5:27b به Ollama برسد.
پروفایل مدل محلی سبک
برخی مدلهای محلی میتوانند به promptهای ساده پاسخ دهند، اما با سطح کامل ابزارهای agent مشکل دارند. پیش از تغییر تنظیمات سراسری runtime، ابتدا ابزارها و زمینه را محدود کنید.
{ agents: { list: [ { id: "local", experimental: { localModelLean: true, }, model: { primary: "ollama/gemma4" }, }, ], }, models: { providers: { ollama: { baseUrl: "http://127.0.0.1:11434", apiKey: "ollama-local", api: "ollama", contextWindow: 32768, models: [ { id: "gemma4", name: "gemma4", input: ["text"], params: { num_ctx: 32768 }, compat: { supportsTools: false }, }, ], }, }, },}فقط زمانی از compat.supportsTools: false استفاده کنید که مدل یا سرور بهطور قابل اتکا روی schemaهای ابزار شکست میخورد. این کار قابلیت agent را با پایداری معاوضه میکند.
localModelLean ابزارهای مرورگر، cron و پیام را از سطح مستقیم agent حذف میکند و catalogهای بزرگتر را بهجز زمانی که یک اجرا باید معناشناسی تحویل مستقیم پیام را حفظ کند، پشت کنترلهای ساختاریافته Tool Search پیشفرض میبرد؛ اما زمینه runtime یا حالت thinking مربوط به Ollama را تغییر نمیدهد. برای مدلهای thinking کوچک به سبک Qwen که در loop میافتند یا بودجه پاسخ خود را صرف reasoning پنهان میکنند، آن را با params.num_ctx صریح و params.thinking: false همراه کنید.
انتخاب مدل
پس از پیکربندی، همه مدلهای Ollama شما در دسترس هستند:
{ agents: { defaults: { model: { primary: "ollama/gpt-oss:20b", fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"], }, }, },}شناسههای provider سفارشی Ollama نیز پشتیبانی میشوند. وقتی یک ارجاع مدل از
پیشوند provider فعال استفاده میکند، مانند ollama-spark/qwen3:32b، OpenClaw فقط همان
پیشوند را پیش از فراخوانی Ollama حذف میکند تا سرور qwen3:32b را دریافت کند.
برای مدلهای محلی کند، پیش از افزایش timeout کل runtime مربوط به agent، تنظیم درخواست در محدوده provider را ترجیح دهید:
{ models: { providers: { ollama: { timeoutSeconds: 300, models: [ { id: "gemma4:26b", name: "gemma4:26b", params: { keep_alive: "15m" }, }, ], }, }, },}timeoutSeconds روی درخواست HTTP مدل اعمال میشود، شامل راهاندازی اتصال،
headerها، streaming بدنه، و کل abort مربوط به guarded-fetch. params.keep_alive
در درخواستهای بومی /api/chat بهعنوان keep_alive سطح بالا به Ollama فرستاده میشود؛
وقتی زمان بارگذاری نوبت اول گلوگاه است، آن را برای هر مدل تنظیم کنید.
تأیید سریع
# Ollama daemon visible to this machinecurl http://127.0.0.1:11434/api/tags # OpenClaw catalog and selected modelopenclaw models list --provider ollamaopenclaw models status # Direct model smokeopenclaw infer model run \ --model ollama/gemma4 \ --prompt "Reply with exactly: ok"برای میزبانهای راهدور، 127.0.0.1 را با میزبان استفادهشده در baseUrl جایگزین کنید. اگر curl کار میکند اما OpenClaw نه، بررسی کنید که آیا Gateway روی ماشین، container یا حساب سرویس دیگری اجرا میشود یا نه.
Ollama Web Search
OpenClaw از Ollama Web Search بهعنوان provider همراه web_search پشتیبانی میکند.
| ویژگی | جزئیات |
|---|---|
| میزبان | از میزبان Ollama پیکربندیشده شما استفاده میکند (models.providers.ollama.baseUrl وقتی تنظیم شده باشد، وگرنه http://127.0.0.1:11434)؛ https://ollama.com مستقیماً از API میزبانیشده استفاده میکند |
| احراز هویت | برای میزبانهای محلی Ollama که وارد شدهاند بدون کلید است؛ برای جستوجوی مستقیم https://ollama.com یا میزبانهای محافظتشده با احراز هویت، OLLAMA_API_KEY یا احراز هویت provider پیکربندیشده استفاده میشود |
| الزام | میزبانهای محلی/خودمیزبان باید در حال اجرا باشند و با ollama signin وارد شده باشند؛ جستوجوی میزبانیشده مستقیم به baseUrl: "https://ollama.com" بههمراه یک کلید API واقعی Ollama نیاز دارد |
در طول openclaw onboard یا openclaw configure --section web، Ollama Web Search را انتخاب کنید، یا تنظیم کنید:
{ tools: { web: { search: { provider: "ollama", }, }, },}برای جستوجوی میزبانیشده مستقیم از طریق Ollama Cloud:
{ models: { providers: { ollama: { baseUrl: "https://ollama.com", apiKey: "OLLAMA_API_KEY", api: "ollama", models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }], }, }, }, tools: { web: { search: { provider: "ollama" }, }, },}برای daemon محلی واردشده، OpenClaw از proxy مربوط به /api/experimental/web_search همان daemon استفاده میکند. برای https://ollama.com، endpoint میزبانیشده /api/web_search را مستقیماً فراخوانی میکند.
پیکربندی پیشرفته
حالت قدیمی سازگار با OpenAI
اگر لازم است بهجای آن از endpoint سازگار با OpenAI استفاده کنید (برای مثال پشت proxy که فقط از قالب OpenAI پشتیبانی میکند)، api: "openai-completions" را صریحاً تنظیم کنید:
{ models: { providers: { ollama: { baseUrl: "http://ollama-host:11434/v1", api: "openai-completions", injectNumCtxForOpenAICompat: true, // default: true apiKey: "ollama-local", models: [...] } } }}این حالت ممکن است همزمان از streaming و فراخوانی ابزار پشتیبانی نکند. شاید لازم باشد streaming را با params: { streaming: false } در پیکربندی مدل غیرفعال کنید.
وقتی api: "openai-completions" با Ollama استفاده میشود، OpenClaw بهطور پیشفرض options.num_ctx را تزریق میکند تا Ollama بیسروصدا به پنجره زمینه 4096 برنگردد. اگر proxy/upstream شما فیلدهای ناشناخته options را رد میکند، این رفتار را غیرفعال کنید:
{ models: { providers: { ollama: { baseUrl: "http://ollama-host:11434/v1", api: "openai-completions", injectNumCtxForOpenAICompat: false, apiKey: "ollama-local", models: [...] } } }}پنجرههای زمینه
برای مدلهای کشفشده بهصورت خودکار، OpenClaw در صورت موجود بودن از پنجره زمینه گزارششده توسط Ollama استفاده میکند، از جمله مقادیر بزرگتر PARAMETER num_ctx از Modelfileهای سفارشی. در غیر این صورت به پنجره زمینه پیشفرض Ollama که OpenClaw استفاده میکند برمیگردد.
میتوانید پیشفرضهای سطح ارائهدهندهی contextWindow، contextTokens و maxTokens را برای هر مدل زیر آن ارائهدهندهی Ollama تنظیم کنید، سپس در صورت نیاز آنها را برای هر مدل بازنویسی کنید. contextWindow بودجهی پرامپت و Compaction در OpenClaw است. درخواستهای بومی Ollama، options.num_ctx را تنظیمنشده میگذارند مگر اینکه params.num_ctx را صراحتاً پیکربندی کنید، تا Ollama بتواند پیشفرض خودش را بر اساس مدل، OLLAMA_CONTEXT_LENGTH یا VRAM اعمال کند. برای محدود کردن یا اجبار زمینهی زمان اجرای هر درخواست Ollama بدون بازسازی Modelfile، params.num_ctx را تنظیم کنید؛ مقادیر نامعتبر، صفر، منفی و غیرمتناهی نادیده گرفته میشوند. اگر یک پیکربندی قدیمیتر را ارتقا دادهاید که فقط از contextWindow یا maxTokens برای اجبار زمینهی درخواست بومی Ollama استفاده میکرد، openclaw doctor --fix را اجرا کنید تا آن بودجههای صریح ارائهدهنده یا مدل را در params.num_ctx کپی کند. آداپتر سازگار با OpenAI برای Ollama همچنان بهطور پیشفرض options.num_ctx را از params.num_ctx یا contextWindow پیکربندیشده تزریق میکند؛ اگر بالادستی شما options را رد میکند، این رفتار را با injectNumCtxForOpenAICompat: false غیرفعال کنید.
ورودیهای مدل بومی Ollama همچنین گزینههای رایج زمان اجرای Ollama را زیر params میپذیرند، از جمله temperature، top_p، top_k، min_p، num_predict، stop، repeat_penalty، num_batch، num_thread و use_mmap. OpenClaw فقط کلیدهای درخواست Ollama را ارسال میکند، بنابراین پارامترهای زمان اجرای OpenClaw مانند streaming به Ollama نشت نمیکنند. برای ارسال think سطحبالای Ollama از params.think یا params.thinking استفاده کنید؛ false تفکر در سطح API را برای مدلهای تفکرمحور سبک Qwen غیرفعال میکند.
{ models: { providers: { ollama: { contextWindow: 32768, models: [ { id: "llama3.3", contextWindow: 131072, maxTokens: 65536, params: { num_ctx: 32768, temperature: 0.7, top_p: 0.9, thinking: false, }, } ] } } }}agents.defaults.models["ollama/<model>"].params.num_ctx در سطح هر مدل نیز کار میکند. اگر هر دو پیکربندی شده باشند، ورودی صریح مدلِ ارائهدهنده بر پیشفرض agent برتری دارد.
کنترل تفکر
برای مدلهای بومی Ollama، OpenClaw کنترل تفکر را همانطور که Ollama انتظار دارد ارسال میکند: think در سطح بالا، نه options.think. مدلهای کشفشدهی خودکار که پاسخ /api/show آنها قابلیت thinking را شامل میشود، /think low، /think medium، /think high و /think max را ارائه میکنند؛ مدلهای بدون تفکر فقط /think off را ارائه میکنند.
openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking lowهمچنین میتوانید یک پیشفرض مدل تنظیم کنید:
{ agents: { defaults: { models: { "ollama/gemma4": { thinking: "low", }, }, }, },}params.think یا params.thinking در سطح هر مدل میتواند تفکر API در Ollama را برای یک مدل پیکربندیشدهی مشخص غیرفعال یا اجباری کند. OpenClaw این پارامترهای صریح مدل را هنگامی که اجرای فعال فقط پیشفرض ضمنی off را دارد حفظ میکند؛ فرمانهای زمان اجرا که off نیستند، مانند /think medium، همچنان اجرای فعال را بازنویسی میکنند.
مدلهای استدلالی
OpenClaw مدلهایی با نامهایی مانند deepseek-r1، reasoning یا think را بهطور پیشفرض دارای قابلیت استدلال در نظر میگیرد.
ollama pull deepseek-r1:32bبه پیکربندی اضافهای نیاز نیست. OpenClaw آنها را بهصورت خودکار علامتگذاری میکند.
هزینههای مدل
Ollama رایگان است و بهصورت محلی اجرا میشود، بنابراین همهی هزینههای مدل روی ۰ دلار تنظیم میشوند. این موضوع هم برای مدلهای کشفشدهی خودکار و هم برای مدلهای تعریفشدهی دستی صدق میکند.
جاسازیهای حافظه
Plugin همراه Ollama یک ارائهدهندهی جاسازی حافظه برای
جستوجوی حافظه ثبت میکند. این ارائهدهنده از URL پایهی Ollama
و کلید API پیکربندیشده استفاده میکند، endpoint فعلی /api/embed در Ollama را فراخوانی میکند و در صورت امکان
چندین قطعهی حافظه را در یک درخواست input دستهبندی میکند.
وقتی proxy.enabled=true باشد، درخواستهای جاسازی حافظهی Ollama به مبدأ دقیق
host-local loopback که از baseUrl پیکربندیشده مشتق شده است، بهجای پراکسی هدایتشدهی مدیریتشده، از
مسیر مستقیم محافظتشدهی OpenClaw استفاده میکنند. نام میزبان پیکربندیشده باید خودش localhost یا یک literal آدرس IP loopback باشد؛
نامهای DNS که صرفاً به loopback resolve میشوند همچنان از مسیر پراکسی مدیریتشده استفاده میکنند.
میزبانهای LAN، tailnet، شبکهی خصوصی و عمومی Ollama نیز در
مسیر پراکسی مدیریتشده باقی میمانند. تغییرمسیرها به میزبان یا درگاه دیگر اعتماد را به ارث نمیبرند.
اپراتورها همچنان میتوانند تنظیم سراسری proxy.loopbackMode: "proxy" را برای
ارسال ترافیک loopback از طریق پراکسی، یا proxy.loopbackMode: "block" را
برای رد کردن اتصالهای loopback پیش از باز کردن اتصال تنظیم کنند؛ برای اثر
سراسری این تنظیم در سطح فرایند، پراکسی مدیریتشده را ببینید.
| ویژگی | مقدار |
|---|---|
| مدل پیشفرض | nomic-embed-text |
| دریافت خودکار | بله — اگر مدل جاسازی بهصورت محلی موجود نباشد، بهطور خودکار دریافت میشود |
جاسازیهای زمان پرسوجو برای مدلهایی که به پیشوندهای بازیابی نیاز دارند یا آنها را توصیه میکنند، از این پیشوندها استفاده میکنند، از جمله nomic-embed-text، qwen3-embedding و mxbai-embed-large. دستههای سند حافظه خام باقی میمانند تا نمایههای موجود به مهاجرت قالب نیاز نداشته باشند.
برای انتخاب Ollama بهعنوان ارائهدهندهی جاسازی جستوجوی حافظه:
{ agents: { defaults: { memorySearch: { provider: "ollama", remote: { // Default for Ollama. Raise on larger hosts if reindexing is too slow. nonBatchConcurrency: 1, }, }, }, },}برای یک میزبان جاسازی راهدور، احراز هویت را محدود به همان میزبان نگه دارید:
{ agents: { defaults: { memorySearch: { provider: "ollama", model: "nomic-embed-text", remote: { baseUrl: "http://gpu-box.local:11434", apiKey: "ollama-local", nonBatchConcurrency: 2, }, }, }, },}پیکربندی استریم
یکپارچهسازی Ollama در OpenClaw بهطور پیشفرض از API بومی Ollama (/api/chat) استفاده میکند که بهطور کامل از استریم و فراخوانی ابزار بهصورت همزمان پشتیبانی میکند. به پیکربندی ویژهای نیاز نیست.
برای درخواستهای بومی /api/chat، OpenClaw همچنین کنترل تفکر را مستقیماً به Ollama ارسال میکند: /think off و openclaw agent --thinking off، مگر اینکه مقدار صریح مدل params.think/params.thinking پیکربندی شده باشد، think: false را در سطح بالا ارسال میکنند، در حالی که /think low|medium|high رشتهی تلاش think متناظر را در سطح بالا ارسال میکند. /think max به بالاترین تلاش بومی Ollama، یعنی think: "high"، نگاشت میشود.
عیبیابی
حلقهی خرابی WSL2 (راهاندازیهای مجدد تکراری)
در WSL2 همراه با NVIDIA/CUDA، نصبکنندهی رسمی لینوکس Ollama یک واحد systemd با نام ollama.service و Restart=always ایجاد میکند. اگر این سرویس بهصورت خودکار شروع شود و هنگام بوت WSL2 یک مدل متکی به GPU را بارگذاری کند، Ollama میتواند هنگام بارگذاری مدل، حافظهی میزبان را pin کند. بازیابی حافظهی Hyper-V همیشه نمیتواند آن صفحههای pinشده را بازپس بگیرد، بنابراین Windows میتواند VM مربوط به WSL2 را خاتمه دهد، systemd دوباره Ollama را شروع میکند و حلقه تکرار میشود.
شواهد رایج:
- راهاندازیهای مجدد یا خاتمههای تکراری WSL2 از سمت Windows
- CPU بالا در
app.sliceیاollama.serviceکمی پس از شروع WSL2 - SIGTERM از systemd بهجای رویداد OOM-killer در Linux
OpenClaw وقتی WSL2، فعال بودن ollama.service با Restart=always و نشانگرهای قابلمشاهدهی CUDA را تشخیص دهد، هنگام شروع یک هشدار ثبت میکند.
راهکار کاهش اثر:
sudo systemctl disable ollamaاین را در سمت Windows به %USERPROFILE%\.wslconfig اضافه کنید، سپس wsl --shutdown را اجرا کنید:
[experimental]autoMemoryReclaim=disabledدر محیط سرویس Ollama یک keep-alive کوتاهتر تنظیم کنید، یا Ollama را فقط وقتی به آن نیاز دارید بهصورت دستی شروع کنید:
export OLLAMA_KEEP_ALIVE=5mollama serveollama/ollama#11317 را ببینید.
Ollama تشخیص داده نمیشود
مطمئن شوید Ollama در حال اجراست و OLLAMA_API_KEY را تنظیم کردهاید (یا یک نمایهی احراز هویت دارید)، و اینکه یک ورودی صریح models.providers.ollama تعریف نکردهاید:
ollama serveبررسی کنید API در دسترس است:
curl http://localhost:11434/api/tagsهیچ مدلی در دسترس نیست
اگر مدل شما فهرست نشده است، یا مدل را بهصورت محلی دریافت کنید یا آن را صراحتاً در models.providers.ollama تعریف کنید.
ollama list # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3 # Or another modelاتصال رد شد
بررسی کنید Ollama روی درگاه درست در حال اجراست:
# Check if Ollama is runningps aux | grep ollama # Or restart Ollamaollama serveمیزبان راهدور با curl کار میکند اما با OpenClaw نه
از همان ماشین و زمان اجرایی که Gateway را اجرا میکند بررسی کنید:
openclaw gateway status --deepcurl http://ollama-host:11434/api/tagsعلتهای رایج:
baseUrlبهlocalhostاشاره میکند، اما Gateway در Docker یا روی میزبان دیگری اجرا میشود.- URL از
/v1استفاده میکند که بهجای رفتار بومی Ollama، رفتار سازگار با OpenAI را انتخاب میکند. - میزبان راهدور در سمت Ollama به تغییرات firewall یا binding شبکهی LAN نیاز دارد.
- مدل روی daemon لپتاپ شما موجود است اما روی daemon راهدور موجود نیست.
مدل JSON ابزار را بهصورت متن خروجی میدهد
این معمولاً یعنی ارائهدهنده از حالت سازگار با OpenAI استفاده میکند یا مدل نمیتواند schemaهای ابزار را مدیریت کند.
حالت بومی Ollama را ترجیح دهید:
{ models: { providers: { ollama: { baseUrl: "http://ollama-host:11434", api: "ollama", }, }, },}اگر یک مدل محلی کوچک همچنان روی schemaهای ابزار شکست میخورد، روی ورودی آن مدل compat.supportsTools: false را تنظیم کنید و دوباره آزمایش کنید.
Kimi یا GLM نمادهای درهمریخته برمیگرداند
پاسخهای میزبانیشدهی Kimi/GLM که طولانی و شامل دنبالههای نمادین غیرزبانی هستند، بهجای یک پاسخ موفق assistant، بهعنوان خروجی ناموفق ارائهدهنده در نظر گرفته میشوند. این اجازه میدهد retry، fallback یا مدیریت خطای معمول بدون ماندگار کردن متن خراب در session وارد عمل شود.
اگر این اتفاق تکرار شد، نام خام مدل، فایل session فعلی و اینکه اجرا از Cloud + Local یا Cloud only استفاده کرده است را ثبت کنید، سپس یک session تازه و یک مدل fallback را امتحان کنید:
openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4مدل محلی سرد timeout میشود
مدلهای محلی بزرگ ممکن است پیش از شروع استریم به یک بارگذاری اولیهی طولانی نیاز داشته باشند. timeout را محدود به ارائهدهندهی Ollama نگه دارید و در صورت تمایل از Ollama بخواهید مدل را بین نوبتها بارگذاریشده نگه دارد:
{ models: { providers: { ollama: { timeoutSeconds: 300, models: [ { id: "gemma4:26b", name: "gemma4:26b", params: { keep_alive: "15m" }, }, ], }, }, },}اگر خود میزبان در پذیرش اتصالها کند باشد، timeoutSeconds همچنین مهلت اتصال محافظتشده Undici را برای این ارائهدهنده افزایش میدهد.
مدل با زمینه بزرگ بیش از حد کند است یا حافظه کم میآورد
بسیاری از مدلهای Ollama زمینههایی را اعلام میکنند که بزرگتر از آناند که سختافزار شما بتواند بهراحتی اجرا کند. Ollama بومی از پیشفرض زمینه زمان اجرای خود Ollama استفاده میکند، مگر اینکه params.num_ctx را تنظیم کنید. وقتی تأخیر قابل پیشبینی برای نخستین توکن میخواهید، هم بودجه OpenClaw و هم زمینه درخواست Ollama را محدود کنید:
{ models: { providers: { ollama: { contextWindow: 32768, maxTokens: 8192, models: [ { id: "qwen3.5:9b", name: "qwen3.5:9b", params: { num_ctx: 32768, thinking: false }, }, ], }, }, },}اگر OpenClaw اعلان بیش از حدی ارسال میکند، ابتدا contextWindow را کاهش دهید. اگر Ollama در حال بارگذاری زمینه زمان اجرایی است که برای دستگاه بیش از حد بزرگ است، params.num_ctx را کاهش دهید. اگر تولید بیش از حد طول میکشد، maxTokens را کاهش دهید.