Ollama

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

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

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

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

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

• کلید سطح ارائه‌دهنده فقط به میزبان همان ارائه‌دهنده ارسال می‌شود.
• agents.*.memorySearch.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, // default: true        apiKey: "ollama-local",        models: [...]      }    }  }}

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

OpenClaw در این حالت به‌طور پیش‌فرض options.num_ctx را تزریق می‌کند تا Ollama بی‌سروصدا به زمینهٔ ۴۰۹۶ توکنی برنگردد. اگر پراکسی شما فیلدهای ناشناختهٔ 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، options.num_ctx را تنظیم‌نشده باقی می‌گذارند، مگر اینکه params.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 می‌پذیرند که به‌عنوان options بومی /api/chat ارسال می‌شوند: 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 را دارد، آن پیکربندی صریح را حفظ می‌کند؛ بااین‌حال، یک فرمان زمان اجرا با مقداری غیر از 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 باشد، درخواست‌های تعبیه به مبدأ دقیق local loopback میزبان که از baseUrl پیکربندی‌شده به دست آمده است، به‌جای پراکسی هدایت مدیریت‌شده از مسیر مستقیم محافظت‌شده OpenClaw استفاده می‌کنند. نام میزبان پیکربندی‌شده باید خودِ localhost یا یک نشانی IP صریح loopback باشد — نام‌های DNS که صرفاً به loopback تفکیک می‌شوند همچنان از مسیر پراکسی مدیریت‌شده استفاده می‌کنند. میزبان‌های Ollama در LAN، tailnet، شبکه خصوصی و عمومی همیشه در مسیر پراکسی مدیریت‌شده باقی می‌مانند و تغییر مسیر به میزبان/درگاهی دیگر، اعتماد را به ارث نمی‌برد. proxy.loopbackMode: "proxy" ترافیک loopback را در هر صورت از پراکسی عبور می‌دهد؛ proxy.loopbackMode: "block" پیش از اتصال آن را رد می‌کند — به پراکسی مدیریت‌شده مراجعه کنید.

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

{  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 به‌طور پیش‌فرض از 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، نصب‌کننده رسمی لینوکس 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 لینوکس.

هنگامی که 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  # See what's installedollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Or another model

از همان ماشین و محیط اجرایی که 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 را کاهش دهید.