Ollama

نشانی‌های Ollama مربوط به loopback، شبکه خصوصی، .local و نام میزبان ساده به توکن حامل واقعی نیاز ندارند. OpenClaw برای این موارد از نشانگر ollama-local استفاده می‌کند.

میزبان‌های عمومی راه دور و https://ollama.com به اعتبارنامه واقعی نیاز دارند: OLLAMA_API_KEY، یک نمایه احراز هویت یا apiKey ارائه‌دهنده. برای استفاده مستقیم میزبانی‌شده، ارائه‌دهنده ollama-cloud را ترجیح دهید.

ارائه‌دهنده سفارشی دارای api: "ollama" از همین قواعد پیروی می‌کند. برای نمونه، ارائه‌دهنده ollama-remote که به یک میزبان خصوصی LAN اشاره دارد می‌تواند از apiKey: "ollama-local" استفاده کند؛ زیرعامل‌ها این نشانگر را از طریق هوک ارائه‌دهنده Ollama حل می‌کنند، نه اینکه آن را اعتبارنامه‌ای مفقود تلقی کنند. memory.search.provider نیز می‌تواند به یک شناسه سفارشی ارائه‌دهنده اشاره کند تا تعبیه‌ها از همان نقطه پایانی Ollama استفاده کنند.

auth-profiles.json اعتبارنامه یک شناسه ارائه‌دهنده را ذخیره می‌کند؛ تنظیمات نقطه پایانی (baseUrl، api، مدل‌ها، سرآیندها و مهلت‌های زمانی) را در models.providers.<id> قرار دهید. فایل‌های تخت قدیمی مانند { "ollama-windows": { "apiKey": "ollama-local" } } قالب زمان اجرا نیستند؛ openclaw doctor --fix آن‌ها را همراه با تهیه نسخه پشتیبان، به یک نمایه معیار کلید API در ollama-windows:default بازنویسی می‌کند. مقدار baseUrl در آن فایل قدیمی زائد است و باید به پیکربندی ارائه‌دهنده منتقل شود.

احراز هویت حامل برای تعبیه‌های حافظه Ollama به میزبانی محدود است که برای آن تعریف شده است:

• کلید سطح ارائه‌دهنده فقط به میزبان همان ارائه‌دهنده ارسال می‌شود.
• memory.search.remote.apiKey و بازنویسی‌های هر عامل فقط به میزبان راه دور تعبیه مربوط به خود ارسال می‌شوند.
• مقدار صرفاً محیطی OLLAMA_API_KEY به‌عنوان قرارداد Ollama Cloud در نظر گرفته می‌شود و به‌طور پیش‌فرض به میزبان‌های محلی یا خودمیزبان ارسال نمی‌شود.

Ollama روی همان دستگاه Gateway، به‌طور خودکار کشف می‌شود:

ollama serveollama pull gemma4export OLLAMA_API_KEY="ollama-local"openclaw models list --provider ollamaopenclaw models set ollama/gemma4

مگر اینکه به مدل‌های دستی نیاز داشته باشید، بلوک models.providers.ollama را اضافه نکنید.

{  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 ارسال می‌شود. وقتی سخت‌افزار نمی‌تواند زمینه کامل اعلام‌شده مدل را اجرا کند، آن‌ها را هم‌راستا نگه دارید.

بدون دیمن محلی، مستقیماً از مدل‌های میزبانی‌شده استفاده کنید:

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" },    },  },}

برای استفاده از شناسه ارائه‌دهنده اختصاصی ollama-cloud به‌جای این ساختار، به Ollama Cloud مراجعه کنید.

هنگام اجرای بیش از یک سرور Ollama از شناسه‌های سفارشی ارائه‌دهنده استفاده کنید؛ هرکدام میزبان، مدل‌ها، احراز هویت و مهلت زمانی مخصوص خود را دارند.

{  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 پیش از فراخوانی Ollama، پیشوند ارائه‌دهنده فعال را حذف می‌کند (و در صورت نبود آن به پیشوند ساده ollama/ برمی‌گردد)، بنابراین ollama-large/qwen3.5:27b به‌شکل qwen3.5:27b به Ollama می‌رسد.

برخی مدل‌های محلی از عهده پرامپت‌های ساده برمی‌آیند، اما با مجموعه کامل ابزارهای عامل مشکل دارند. پیش از تغییر تنظیمات سراسری زمان اجرای عامل، ابزارها و زمینه را محدود کنید:

{  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 استفاده کنید که مدل یا سرور به‌طور قابل‌اعتماد در طرح‌واره‌های ابزار شکست می‌خورد — این گزینه قابلیت‌های عامل را با پایداری معاوضه می‌کند. localModelLean ابزارهای سنگین مرورگر، cron، پیام، تولید رسانه، صوت و PDF را، مگر در صورت نیاز صریح، از سطح مستقیم عامل حذف می‌کند و کاتالوگ‌های بزرگ‌تر را پشت جست‌وجوی ابزار قرار می‌دهد. این گزینه زمینه زمان اجرای Ollama یا حالت تفکر آن را تغییر نمی‌دهد. برای مدل‌های کوچک متفکر به‌سبک Qwen که وارد حلقه می‌شوند یا بودجه خود را صرف استدلال پنهان می‌کنند، آن را با params.num_ctx و params.thinking: false همراه کنید.

برای پروکسی پشت /v1/chat/completions، مقدار api: "openai-completions" را صریحاً تنظیم کنید:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // پیش‌فرض: true        apiKey: "ollama-local",        models: [...]      }    }  }}

این حالت ممکن است از جریان‌دهی و فراخوانی ابزار به‌طور هم‌زمان پشتیبانی نکند؛ شاید لازم باشد params: { streaming: false } را روی مدل تنظیم کنید.

OpenClaw در این حالت به‌طور پیش‌فرض options.num_ctx را تزریق می‌کند تا Ollama بی‌سروصدا به زمینه 4096 توکنی برنگردد. اگر پروکسی شما فیلدهای ناشناخته options را رد می‌کند، آن را غیرفعال کنید:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

برای مدل‌های کشف‌شده خودکار، OpenClaw از پنجره زمینه‌ای استفاده می‌کند که /api/show گزارش می‌دهد، از جمله مقادیر بزرگ‌تر PARAMETER num_ctx از Modelfileهای سفارشی؛ در غیر این صورت به پنجره زمینه پیش‌فرض Ollama در OpenClaw برمی‌گردد.

مقادیر contextWindow، contextTokens و maxTokens در سطح ارائه‌دهنده، پیش‌فرض‌های همه مدل‌های زیرمجموعه آن ارائه‌دهنده را تعیین می‌کنند و می‌توان آن‌ها را برای هر مدل بازنویسی کرد. contextWindow بودجه پرامپت/Compaction خود OpenClaw است. درخواست‌های بومی /api/chat، مگر اینکه params.num_ctx را صریحاً تنظیم کنید، options.num_ctx را تنظیم‌نشده باقی می‌گذارند؛ بنابراین Ollama پیش‌فرض خود مدل، OLLAMA_CONTEXT_LENGTH یا پیش‌فرض مبتنی بر VRAM را اعمال می‌کند؛ مقادیر نامعتبر، صفر، منفی یا نامتناهی params.num_ctx نادیده گرفته می‌شوند. اگر یک پیکربندی قدیمی فقط از contextWindow/maxTokens برای اجبار زمینه درخواست بومی استفاده می‌کرد، openclaw doctor --fix را اجرا کنید تا آن مقادیر در params.num_ctx کپی شوند. آداپتور سازگار با OpenAI همچنان به‌طور پیش‌فرض options.num_ctx را از params.num_ctx یا contextWindow پیکربندی‌شده تزریق می‌کند؛ اگر سرویس بالادستی options را رد می‌کند، آن را با injectNumCtxForOpenAICompat: false غیرفعال کنید.

ورودی‌های مدل بومی همچنین گزینه‌های رایج زمان اجرای Ollama را زیر params می‌پذیرند که به‌صورت /api/chat options بومی ارسال می‌شوند: num_keep، seed، num_predict، top_k، top_p، min_p، typical_p، repeat_last_n، temperature، repeat_penalty، presence_penalty، frequency_penalty، stop، num_batch، num_gpu، main_gpu، use_mmap و num_thread. چند کلید (format، keep_alive، truncate، shift) به‌جای قرار گرفتن زیر options، به‌صورت فیلدهای سطح بالای درخواست ارسال می‌شوند. OpenClaw فقط همین کلیدهای درخواست Ollama را ارسال می‌کند، بنابراین پارامترهای مختص زمان اجرا مانند streaming هرگز به Ollama ارسال نمی‌شوند. برای تنظیم think در سطح بالا از 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 نیز کار می‌کند؛ اگر هر دو تنظیم شده باشند، ورودی صریح مدل ارائه‌دهنده اولویت دارد.

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 را برای مدلی مشخص غیرفعال یا اجباری کند. OpenClaw این پیکربندی صریح را زمانی حفظ می‌کند که اجرای فعال فقط پیش‌فرض ضمنی off را داشته باشد؛ یک فرمان زمان اجرا که خاموش نیست، مانند /think medium، همچنان آن را بازنویسی می‌کند. درخواست تفکر با مقدار درست هرگز به مدلی که صراحتاً با reasoning: false علامت‌گذاری شده است ارسال نمی‌شود؛ درخواست think: false همیشه، بدون توجه به این مورد، ارسال می‌شود.

مدل‌هایی با نام deepseek-r1، reasoning، reason یا think به‌طور پیش‌فرض دارای قابلیت استدلال در نظر گرفته می‌شوند — نیازی به پیکربندی اضافی نیست:

ollama pull deepseek-r1:32b

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

Plugin همراه Ollama یک ارائه‌دهنده تعبیه حافظه برای جست‌وجوی حافظه ثبت می‌کند. این ارائه‌دهنده از URL پایه و کلید API پیکربندی‌شده Ollama استفاده می‌کند، /api/embed را فراخوانی می‌کند و در صورت امکان، چند قطعه حافظه را در یک درخواست input به‌صورت دسته‌ای ارسال می‌کند.

وقتی proxy.enabled=true باشد، درخواست‌های تعبیه به مبدأ حلقه‌بازگشت دقیقاً محلیِ میزبان که از baseUrl پیکربندی‌شده مشتق شده است، به‌جای پروکسی هدایت مدیریت‌شده از مسیر مستقیم محافظت‌شده OpenClaw استفاده می‌کنند. نام میزبان پیکربندی‌شده باید خودِ localhost یا یک نشانی IP صریح حلقه‌بازگشت باشد — نام‌های DNS که صرفاً به حلقه‌بازگشت تفکیک می‌شوند، همچنان از مسیر پروکسی مدیریت‌شده استفاده می‌کنند. میزبان‌های Ollama در LAN، tailnet، شبکه خصوصی و عمومی همیشه در مسیر پروکسی مدیریت‌شده باقی می‌مانند و تغییر مسیر به میزبان/درگاه دیگری این اعتماد را به ارث نمی‌برد. proxy.loopbackMode: "proxy" ترافیک حلقه‌بازگشت را بااین‌حال از پروکسی عبور می‌دهد؛ proxy.loopbackMode: "block" پیش از اتصال آن را رد می‌کند — پروکسی مدیریت‌شده را ببینید.

تعبیه‌های زمان پرس‌وجو برای مدل‌هایی که به پیشوندهای بازیابی نیاز دارند یا آن‌ها را توصیه می‌کنند، از این پیشوندها استفاده می‌کنند: nomic-embed-text، qwen3-embedding و mxbai-embed-large. دسته‌های سند خام باقی می‌مانند؛ بنابراین نمایه‌های موجود به مهاجرت قالب نیاز ندارند.

{  memory: {    search: {      provider: "ollama",      remote: {        // پیش‌فرض Ollama. اگر بازنمایه‌سازی در میزبان‌های بزرگ‌تر بیش‌ازحد کند است، آن را افزایش دهید.        nonBatchConcurrency: 1,      },    },  },}

برای میزبان تعبیه راه‌دور، دامنه احراز هویت را به همان میزبان محدود نگه دارید:

{  memory: {    search: {      provider: "ollama",      model: "nomic-embed-text",      remote: {        baseUrl: "http://gpu-box.local:11434",        apiKey: "ollama-local",        nonBatchConcurrency: 2,      },    },  },}

Ollama به‌طور پیش‌فرض از API بومی (/api/chat) استفاده می‌کند که از جریان‌دهی و فراخوانی ابزار به‌طور هم‌زمان پشتیبانی می‌کند — نیازی به پیکربندی ویژه نیست.

برای درخواست‌های بومی، کنترل تفکر مستقیماً ارسال می‌شود: /think off و openclaw agent --thinking off مقدار سطح بالای think: false را ارسال می‌کنند، مگر اینکه params.think/params.thinking صراحتاً پیکربندی شده باشد؛ /think low|medium|high رشته تلاش متناظر را ارسال می‌کند؛ /think max به بالاترین سطح تلاش Ollama، یعنی think: "high"، نگاشت می‌شود.

در WSL2 همراه با NVIDIA/CUDA، نصب‌کننده رسمی Linux برای Ollama یک واحد systemd با نام ollama.service و مقدار Restart=always ایجاد می‌کند. اگر آن سرویس خودکار شروع شود و هنگام راه‌اندازی WSL2 مدلی مبتنی بر GPU را بارگذاری کند، Ollama ممکن است هنگام بارگذاری حافظه میزبان را ثابت نگه دارد؛ بازیابی حافظه Hyper-V همیشه نمی‌تواند آن صفحه‌ها را پس بگیرد، در نتیجه Windows ممکن است ماشین مجازی WSL2 را خاتمه دهد، systemd دوباره Ollama را راه‌اندازی کند و این چرخه تکرار شود.

شواهد: راه‌اندازی مجدد/خاتمه مکرر WSL2، مصرف بالای CPU در app.slice یا ollama.service بلافاصله پس از شروع WSL2، و دریافت SIGTERM از systemd به‌جای پایان‌دهنده OOM در Linux.

OpenClaw وقتی WSL2، فعال‌بودن ollama.service همراه با Restart=always و نشانگرهای قابل‌مشاهده CUDA را تشخیص دهد، یک هشدار هنگام شروع ثبت می‌کند.

راهکار کاهش مشکل:

sudo systemctl disable ollama

در سمت Windows، این مورد را به %USERPROFILE%\.wslconfig اضافه کنید، سپس wsl --shutdown را اجرا کنید:

[experimental]autoMemoryReclaim=disabled

یا زمان زنده‌ماندن را کوتاه کنید / Ollama را فقط هنگام نیاز به‌صورت دستی شروع کنید:

export OLLAMA_KEEP_ALIVE=5mollama serve

ollama/ollama#11317 را ببینید.

تأیید کنید که Ollama در حال اجرا است، OLLAMA_API_KEY (یا یک نمایه احراز هویت) تنظیم شده و models.providers.ollama به‌صورت صریح تعریف نشده است:

ollama servecurl http://localhost:11434/api/tags

مدل را به‌صورت محلی دریافت کنید یا آن را صراحتاً در models.providers.ollama تعریف کنید:

ollama list  # موارد نصب‌شده را ببینیدollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # یا مدلی دیگر

از همان دستگاه و محیط اجرایی که Gateway را اجرا می‌کند بررسی کنید:

openclaw gateway status --deepcurl http://ollama-host:11434/api/tags

علت‌های رایج:

• baseUrl به localhost اشاره می‌کند، اما Gateway در Docker یا میزبان دیگری اجرا می‌شود.
• URL از /v1 استفاده می‌کند و به‌جای رفتار بومی Ollama، رفتار سازگار با OpenAI را انتخاب می‌کند.
• میزبان راه‌دور به تغییرات دیوار آتش یا اتصال LAN نیاز دارد.
• مدل در سرویس پس‌زمینه لپ‌تاپ شما وجود دارد، اما در سرویس راه‌دور نیست.

معمولاً ارائه‌دهنده در حالت سازگار با OpenAI است یا مدل نمی‌تواند طرح‌واره‌های ابزار را مدیریت کند. حالت بومی را ترجیح دهید:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434",        api: "ollama",      },    },  },}

اگر یک مدل کوچک محلی همچنان در طرح‌واره‌های ابزار شکست می‌خورد، compat.supportsTools: false را در ورودی همان مدل تنظیم و دوباره آزمایش کنید.

پاسخ‌های میزبانی‌شده Kimi/GLM که شامل دنباله‌های طولانی و غیرزبانی از نمادها هستند، به‌جای پاسخ موفق، فراخوانی ناموفق ارائه‌دهنده تلقی می‌شوند؛ بنابراین مدیریت عادی تلاش مجدد/جایگزینی/خطا وارد عمل می‌شود و متن خراب در نشست ماندگار نمی‌شود.

اگر دوباره رخ داد، نام مدل، فایل نشست فعلی و اینکه اجرا از Cloud + Local یا Cloud only استفاده کرده است را ثبت کنید؛ سپس یک نشست تازه و مدل جایگزین را امتحان کنید:

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --jsonopenclaw models set ollama/gemma4

مدل‌های بزرگ محلی ممکن است برای نخستین بارگذاری به زمان زیادی نیاز داشته باشند. مهلت زمانی را به ارائه‌دهنده Ollama محدود کنید و در صورت تمایل، مدل را بین نوبت‌ها بارگذاری‌شده نگه دارید:

{  models: {    providers: {      ollama: {        timeoutSeconds: 300,        models: [          {            id: "gemma4:26b",            name: "gemma4:26b",            params: { keep_alive: "15m" },          },        ],      },    },  },}

اگر خود میزبان برای پذیرش اتصال کند است، timeoutSeconds نیز مهلت زمانی اتصال محافظت‌شده این ارائه‌دهنده را افزایش می‌دهد.

بسیاری از مدل‌ها اندازه زمینه‌ای بزرگ‌تر از آنچه سخت‌افزار شما می‌تواند به‌راحتی اجرا کند اعلام می‌کنند. 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 را کاهش دهید.