Ollama

لا تحتاج مضيفات Ollama المحلية ومضيفات LAN إلى رمز حامل حقيقي. يستخدم OpenClaw علامة ollama-local المحلية فقط لعناوين URL الأساسية الخاصة بـ Ollama التي تكون local loopback، أو شبكة خاصة، أو .local، أو اسم مضيف مجرد.

تتطلب المضيفات العامة البعيدة وOllama Cloud (https://ollama.com) بيانات اعتماد حقيقية عبر OLLAMA_API_KEY، أو ملف تعريف مصادقة، أو apiKey الخاص بالموفر. للاستخدام المستضاف المباشر، فضّل الموفر ollama-cloud.

تتبع معرّفات الموفر المخصصة التي تضبط api: "ollama" القواعد نفسها. على سبيل المثال، يمكن لموفر ollama-remote يشير إلى مضيف Ollama خاص على 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 في ذلك الملف ضجيج توافق ويجب نقله إلى إعداد الموفر.

عند استخدام Ollama لتضمينات الذاكرة، تُحدد مصادقة الحامل بنطاق المضيف الذي صُرّح بها فيه:

• يُرسل المفتاح على مستوى الموفر فقط إلى مضيف Ollama الخاص بذلك الموفر.
• يُرسل agents.*.memorySearch.remote.apiKey فقط إلى مضيف التضمين البعيد الخاص به.
• تُعامل قيمة البيئة OLLAMA_API_KEY الصرفة كاصطلاح Ollama Cloud، ولا تُرسل إلى المضيفات المحلية أو ذاتية الاستضافة افتراضيًا.

استخدم هذا عندما يعمل Ollama على الجهاز نفسه مثل Gateway وتريد أن يكتشف OpenClaw النماذج المثبتة تلقائيًا.

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

يبقي هذا المسار الإعدادات في حدها الأدنى. لا تضف كتلة models.providers.ollama إلا إذا كنت تريد تعريف النماذج يدويًا.

استخدم عناوين 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 المستضافة مباشرة.

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 محلي أو على الشبكة المحلية مسجّل الدخول باستخدام 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 واحد. يحصل كل موفر على مضيفه ونماذجه ومصادقته ومهلته ومراجع نماذجه الخاصة.

{  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-large/qwen3.5:27b إلى Ollama باسم qwen3.5:27b.

تستطيع بعض النماذج المحلية الإجابة عن المطالبات البسيطة لكنها تواجه صعوبة مع سطح أدوات الوكيل الكامل. ابدأ بتقييد الأدوات والسياق قبل تغيير إعدادات وقت التشغيل العامة.

{  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 والرسائل من سطح الوكيل المباشر ويضع الكتالوجات الأكبر افتراضيًا خلف عناصر تحكم Tool Search المنظمة إلا عندما يجب أن يحافظ التشغيل على دلالات تسليم الرسائل المباشر، لكنه لا يغير سياق وقت تشغيل Ollama أو وضع التفكير. اقرنه مع params.num_ctx الصريح وparams.thinking: false لنماذج التفكير الصغيرة بأسلوب Qwen التي تدخل في حلقات أو تنفق ميزانية استجابتها على الاستدلال المخفي.

إذا كنت تحتاج إلى استخدام نقطة النهاية المتوافقة مع OpenAI بدلًا من ذلك (على سبيل المثال، خلف وكيل لا يدعم إلا تنسيق OpenAI)، فاضبط 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 } في إعدادات النموذج.

عند استخدام api: "openai-completions" مع Ollama، يحقن 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 نافذة السياق التي يبلّغ عنها Ollama عند توفرها، بما في ذلك قيم PARAMETER num_ctx الأكبر من Modelfiles المخصصة. وإلا فإنه يعود إلى نافذة سياق Ollama الافتراضية التي يستخدمها OpenClaw.

يمكنك تعيين قيم افتراضية على مستوى المزوّد لـ contextWindow وcontextTokens وmaxTokens لكل نموذج ضمن مزوّد Ollama ذلك، ثم تجاوزها لكل نموذج عند الحاجة. contextWindow هي ميزانية OpenClaw للموجّه وCompaction. تترك طلبات 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. ما زال محوّل Ollama المتوافق مع OpenAI يحقن options.num_ctx افتراضيًا من params.num_ctx أو contextWindow المضبوطين؛ عطّل ذلك باستخدام injectNumCtxForOpenAICompat: false إذا كان المنبع لديك يرفض options.

تقبل إدخالات نماذج 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. استخدم params.think أو params.thinking لإرسال think على المستوى الأعلى في Ollama؛ وتؤدي القيمة 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 لكل نموذج. إذا ضُبط كلاهما، فإن إدخال نموذج المزوّد الصريح يتغلّب على الإعداد الافتراضي للوكيل.

بالنسبة إلى نماذج 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 لكل نموذج تعطيل أو فرض تفكير Ollama API لنموذج مضبوط محدد. يحتفظ OpenClaw بمعاملات النموذج الصريحة تلك عندما لا يملك التشغيل النشط إلا القيمة الافتراضية الضمنية off؛ وما زالت أوامر وقت التشغيل غير off مثل /think medium تتجاوز التشغيل النشط.

يتعامل OpenClaw افتراضيًا مع النماذج ذات الأسماء مثل deepseek-r1 أو reasoning أو think على أنها قادرة على الاستدلال.

ollama pull deepseek-r1:32b

لا يلزم أي إعداد إضافي. يضع OpenClaw عليها علامة تلقائيًا.

Ollama مجاني ويعمل محليًا، لذلك تُضبط كل تكاليف النماذج على $0. ينطبق هذا على النماذج المكتشفة تلقائيًا والمحددة يدويًا.

يسجّل Ollama Plugin المضمّن مزوّد تضمينات ذاكرة من أجل بحث الذاكرة. يستخدم عنوان URL الأساسي وAPI key المضبوطين لـ Ollama، ويستدعي نقطة النهاية الحالية /api/embed في Ollama، ويجمّع عدة أجزاء ذاكرة في طلب input واحد متى أمكن.

عندما يكون proxy.enabled=true، تستخدم طلبات تضمين ذاكرة Ollama إلى أصل host-local loopback الدقيق المشتق من baseUrl المضبوط مسار OpenClaw المباشر المحروس بدلًا من وكيل التمرير المدار. يجب أن يكون اسم المضيف المضبوط نفسه localhost أو قيمة IP حرفية لـ loopback؛ أما أسماء DNS التي تُحلّ فقط إلى loopback فتبقى تستخدم مسار الوكيل المدار. كما تبقى مضيفات Ollama على LAN وtailnet والشبكات الخاصة والعامة على مسار الوكيل المدار. لا ترث عمليات إعادة التوجيه إلى مضيف أو منفذ آخر الثقة. ما زال بإمكان المشغّلين تعيين الإعداد العام proxy.loopbackMode: "proxy" لإرسال حركة مرور loopback عبر الوكيل، أو proxy.loopbackMode: "block" لرفض اتصالات loopback قبل فتح اتصال؛ راجع الوكيل المدار لمعرفة الأثر على مستوى العملية بالكامل لهذا الإعداد.

تستخدم التضمينات وقت الاستعلام بادئات الاسترجاع للنماذج التي تتطلبها أو توصي بها، بما في ذلك 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 Ollama API الأصلي (/api/chat) افتراضيًا، وهو يدعم البث واستدعاء الأدوات معًا بالكامل. لا يلزم إعداد خاص.

بالنسبة إلى طلبات /api/chat الأصلية، يمرّر OpenClaw أيضًا التحكم في التفكير مباشرة إلى Ollama: يرسل /think off وopenclaw agent --thinking off القيمة think: false على المستوى الأعلى ما لم تكن قيمة نموذج صريحة params.think/params.thinking مضبوطة، بينما ترسل /think low|medium|high سلسلة جهد think المطابقة على المستوى الأعلى. ويتم ربط /think max بأعلى جهد أصلي في Ollama، وهو think: "high".

على WSL2 مع NVIDIA/CUDA، ينشئ مثبّت Ollama الرسمي لنظام Linux وحدة systemd باسم ollama.service تحتوي على Restart=always. إذا بدأت تلك الخدمة تلقائيًا وحمّلت نموذجًا مدعومًا من GPU أثناء إقلاع WSL2، يمكن أن يثبّت Ollama ذاكرة المضيف أثناء تحميل النموذج. لا يستطيع استرداد ذاكرة Hyper-V دائمًا استعادة تلك الصفحات المثبّتة، لذلك يمكن أن ينهي Windows آلة WSL2 الافتراضية، ثم يبدأ systemd تشغيل Ollama مجددًا، وتتكرر الحلقة.

أدلة شائعة:

• عمليات إعادة تشغيل أو إنهاء متكررة لـ WSL2 من جانب Windows
• استهلاك CPU مرتفع في app.slice أو ollama.service بعد وقت قصير من بدء WSL2
• SIGTERM من systemd بدلًا من حدث Linux OOM-killer

يسجل OpenClaw تحذير بدء تشغيل عندما يكتشف WSL2، وollama.service مفعّلًا مع Restart=always، وواسمات CUDA مرئية.

التخفيف:

sudo systemctl disable ollama

أضف هذا إلى %USERPROFILE%\.wslconfig على جانب Windows، ثم شغّل wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

عيّن مدة keep-alive أقصر في بيئة خدمة Ollama، أو ابدأ Ollama يدويًا فقط عندما تحتاج إليه:

export OLLAMA_KEEP_ALIVE=5mollama serve

راجع ollama/ollama#11317.

تأكد من أن 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

تحقّق من الجهاز ووقت التشغيل نفسيهما اللذين يشغّلان Gateway:

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

أسباب شائعة:

• يشير baseUrl إلى localhost، لكن Gateway يعمل في Docker أو على مضيف آخر.
• يستخدم عنوان URL المسار /v1، ما يختار سلوكًا متوافقًا مع OpenAI بدلًا من Ollama الأصلي.
• يحتاج المضيف البعيد إلى تغييرات في جدار الحماية أو ربط LAN من جانب Ollama.
• النموذج موجود على برنامج الخدمة في حاسوبك المحمول لكنه غير موجود على برنامج الخدمة البعيد.

يعني هذا عادةً أن المزوّد يستخدم وضع التوافق مع OpenAI أو أن النموذج لا يستطيع التعامل مع مخططات الأدوات.

فضّل وضع Ollama الأصلي:

{  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، ويمكنك اختياريًا أن تطلب من 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 },          },        ],      },    },  },}

خفّض contextWindow أولًا إذا كان OpenClaw يرسل موجهًا كبيرًا جدًا. خفّض params.num_ctx إذا كان Ollama يحمّل سياق وقت تشغيل أكبر مما تتحمله الآلة. خفّض maxTokens إذا كان التوليد يستغرق وقتًا طويلًا جدًا.