الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

يدمج OpenClaw مع واجهة Ollama الأصلية (/api/chat) لنماذج السحابة المستضافة وخوادم Ollama المحلية/ذاتية الاستضافة. يمكنك استخدام Ollama بثلاثة أوضاع: Cloud + Local عبر مضيف Ollama قابل للوصول، أو Cloud only عبر https://ollama.com، أو Local only عبر مضيف Ollama قابل للوصول.
مستخدمو Ollama البعيد: لا تستخدم عنوان URL المتوافق مع OpenAI /v1 ‏(http://host:11434/v1) مع OpenClaw. يؤدي ذلك إلى تعطيل استدعاء الأدوات وقد تُخرج النماذج JSON الخاص بالأدوات الخام كنص عادي. استخدم عنوان URL الأصلي لواجهة Ollama API بدلاً من ذلك: baseUrl: "http://host:11434" (بدون /v1).
يستخدم إعداد موفر Ollama المفتاح baseUrl كمفتاح أساسي. يقبل OpenClaw أيضاً baseURL للتوافق مع أمثلة أسلوب OpenAI SDK، لكن يجب أن تفضل الإعدادات الجديدة baseUrl.

​
قواعد المصادقة

لا تحتاج مضيفات Ollama المحلية ومضيفات LAN إلى رمز حامل حقيقي. يستخدم OpenClaw واسم ollama-local المحلي فقط لعناوين URL الأساسية الخاصة بـ Ollama التي تستخدم local loopback والشبكة الخاصة و.local وأسماء المضيف العارية.
تتطلب المضيفات العامة البعيدة وOllama Cloud ‏(https://ollama.com) اعتماداً حقيقياً عبر OLLAMA_API_KEY أو ملف تعريف مصادقة أو apiKey الخاص بالموفر.
تتبع معرّفات الموفر المخصصة التي تضبط 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 سحابي أو محلي عامل.
1

تشغيل الإعداد الأولي

openclaw onboard
اختر Ollama من قائمة الموفرين.
2

اختيار وضعك

  • Cloud + Local — مضيف Ollama محلي إضافة إلى نماذج سحابية تُمرر عبر ذلك المضيف
  • Cloud only — نماذج Ollama مستضافة عبر https://ollama.com
  • Local only — نماذج محلية فقط
3

اختيار نموذج

يطلب Cloud only قيمة OLLAMA_API_KEY ويقترح افتراضيات سحابية مستضافة. يطلب Cloud + Local وLocal only عنوان URL أساسياً لـ Ollama، ويكتشفان النماذج المتاحة، ويسحبان تلقائياً النموذج المحلي المحدد إذا لم يكن متاحاً بعد. عندما يبلغ Ollama عن وسم :latest مثبت مثل gemma4:latest، يعرض الإعداد ذلك النموذج المثبت مرة واحدة بدلاً من عرض كل من gemma4 وgemma4:latest أو سحب الاسم المستعار العاري مرة أخرى. يتحقق Cloud + Local أيضاً مما إذا كان مضيف Ollama هذا مسجلاً دخوله للوصول السحابي.
4

التحقق من توفر النموذج

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-risk

​
نماذج السحابة

يستخدم Cloud + Local مضيف Ollama قابل للوصول كنقطة تحكم لكل من النماذج المحلية والسحابية. هذا هو التدفق الهجين المفضل لدى Ollama.استخدم Cloud + Local أثناء الإعداد. يطلب OpenClaw عنوان URL الأساسي لـ Ollama، ويكتشف النماذج المحلية من ذلك المضيف، ويتحقق مما إذا كان المضيف مسجلاً دخوله للوصول السحابي باستخدام ollama signin. عندما يكون المضيف مسجلاً الدخول، يقترح OpenClaw أيضاً افتراضيات سحابية مستضافة مثل kimi-k2.5:cloud وminimax-m2.7:cloud وglm-5.1:cloud.إذا لم يكن المضيف مسجلاً الدخول بعد، يبقي OpenClaw الإعداد محلياً فقط إلى أن تشغّل ollama signin.

​
اكتشاف النماذج (موفر ضمني)

عندما تضبط OLLAMA_API_KEY (أو ملف تعريف مصادقة) ولا تعرّف models.providers.ollama أو موفراً بعيداً مخصصاً آخر مع api: "ollama"، يكتشف OpenClaw النماذج من نسخة Ollama المحلية على http://127.0.0.1:11434.
السلوكالتفاصيل
استعلام الكتالوجيستعلم /api/tags
اكتشاف القدراتيستخدم عمليات بحث /api/show بأفضل جهد لقراءة contextWindow، ومعلمات num_ctx الموسعة في Modelfile، والقدرات بما فيها الرؤية/الأدوات
نماذج الرؤيةالنماذج التي تبلغ /api/show عن قدرة vision لها تُوسم بأنها قادرة على الصور (input: ["text", "image"])، لذلك يحقن OpenClaw الصور تلقائياً في الموجه
اكتشاف الاستدلاليستخدم قدرات /api/show عند توفرها، بما في ذلك thinking؛ ويعود إلى استدلال من اسم النموذج (r1 وreasoning وthink) عندما يحذف Ollama القدرات
حدود الرموزيضبط maxTokens على سقف الحد الأقصى الافتراضي للرموز في Ollama الذي يستخدمه OpenClaw
التكاليفيضبط كل التكاليف على 0
يتجنب هذا إدخالات النماذج اليدوية مع إبقاء الكتالوج متوافقاً مع نسخة Ollama المحلية. يمكنك استخدام مرجع كامل مثل ollama/<pulled-model>:latest في infer model run المحلي؛ يحل OpenClaw ذلك النموذج المثبت من كتالوج Ollama المباشر دون الحاجة إلى إدخال models.json مكتوب يدوياً. بالنسبة إلى مضيفات Ollama المسجلة الدخول، قد تكون بعض نماذج :cloud قابلة للاستخدام عبر /api/chat و/api/show قبل أن تظهر في /api/tags. عندما تحدد صراحة مرجعاً كاملاً ollama/<model>:cloud، يتحقق OpenClaw من ذلك النموذج المفقود بعينه عبر /api/show ويضيفه إلى كتالوج التشغيل فقط إذا أكد Ollama بيانات النموذج الوصفية. لا تزال الأخطاء المطبعية تفشل كنماذج غير معروفة بدلاً من إنشائها تلقائياً. 
# See what models are available
ollama list
openclaw models list
لاختبار smoke ضيق لتوليد النص يتجنب سطح أدوات الوكيل الكامل، استخدم 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
لا يزال ذلك المسار يستخدم موفر OpenClaw المضبوط والمصادقة والنقل الأصلي لـ Ollama، لكنه لا يبدأ دورة وكيل دردشة ولا يحمّل سياق MCP/الأدوات. إذا نجح هذا بينما تفشل ردود الوكيل العادية، فاستكشف بعد ذلك سعة موجه/أدوات الوكيل الخاصة بالنموذج. لاختبار smoke ضيق لنموذج رؤية على المسار الخفيف نفسه، أضف ملف صورة واحداً أو أكثر إلى infer model run. يرسل هذا الموجه والصورة مباشرة إلى نموذج رؤية 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 \
    --json
يقبل model run --file الملفات المكتشفة كـ image/*، بما في ذلك مدخلات PNG وJPEG وWebP الشائعة. تُرفض الملفات غير الصورية قبل استدعاء Ollama. للتعرف على الكلام، استخدم openclaw infer audio transcribe بدلاً من ذلك. عندما تبدّل محادثة باستخدام /model ollama/<model>، يتعامل OpenClaw مع ذلك كتحديد مستخدم دقيق. إذا كان baseUrl المضبوط لـ Ollama غير قابل للوصول، يفشل الرد التالي بخطأ الموفر بدلاً من الرد بصمت من نموذج احتياطي مضبوط آخر. مهام Cron المعزولة تنفذ فحص أمان محليًا إضافيًا قبل أن تبدأ دورة الوكيل. إذا كان النموذج المحدد يُحل إلى موفر Ollama محلي أو على شبكة خاصة أو .local وكان /api/tags غير قابل للوصول، يسجل OpenClaw تشغيل Cron ذلك كـ skipped مع ollama/<model> المحدد في نص الخطأ. يتم تخزين فحص نقطة النهاية المسبق مؤقتًا لمدة 5 دقائق، لذلك لا تطلق عدة مهام Cron موجهة إلى نفس خادم Ollama المتوقف طلبات نماذج فاشلة كلها. تحقق حيًا من مسار النص المحلي، ومسار البث الأصلي، والتضمينات مقابل Ollama المحلي باستخدام: 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts
لإضافة نموذج جديد، اسحبه ببساطة باستخدام Ollama: 
ollama pull mistral
سيتم اكتشاف النموذج الجديد تلقائيًا وسيكون متاحًا للاستخدام.
إذا عيّنت models.providers.ollama صراحةً، أو كوّنت موفرًا بعيدًا مخصصًا مثل models.providers.ollama-cloud مع api: "ollama"، يتم تخطي الاكتشاف التلقائي ويجب عليك تعريف النماذج يدويًا. لا يزال يتم التعامل مع الموفرين المخصصين عبر loopback مثل http://127.0.0.2:11434 كموفرين محليين. راجع قسم التكوين الصريح أدناه.

​
الرؤية ووصف الصور

يسجل Plugin Ollama المضمن Ollama كموفر قادر على الصور لفهم الوسائط. يتيح هذا لـ OpenClaw توجيه طلبات وصف الصور الصريحة وافتراضيات نماذج الصور المكوّنة عبر نماذج رؤية Ollama المحلية أو المستضافة. للرؤية المحلية، اسحب نموذجًا يدعم الصور: 
ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
ثم تحقق باستخدام infer CLI: 
openclaw infer image describe \
  --file ./photo.jpg \
  --model ollama/qwen2.5vl:7b \
  --json
يجب أن يكون --model مرجعًا كاملًا بصيغة <provider/model>. عند تعيينه، يشغّل openclaw infer image describe ذلك النموذج مباشرة بدلًا من تخطي الوصف لأن النموذج يدعم الرؤية الأصلية. استخدم infer image describe عندما تريد تدفق موفر فهم الصور في OpenClaw، وagents.defaults.imageModel المكوّن، وشكل مخرجات وصف الصور. استخدم infer model run --file عندما تريد فحصًا خامًا لنموذج متعدد الوسائط مع مطالبة مخصصة وصورة واحدة أو أكثر. لجعل Ollama نموذج فهم الصور الافتراضي للوسائط الواردة، كوّن agents.defaults.imageModel: 
{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}
فضّل المرجع الكامل ollama/<model>. إذا كان النموذج نفسه مدرجًا ضمن models.providers.ollama.models مع input: ["text", "image"] ولا يكشف أي موفر صور مكوّن آخر معرّف النموذج المجرد نفسه، يقوم OpenClaw أيضًا بتطبيع مرجع imageModel مجرد مثل qwen2.5vl:7b إلى ollama/qwen2.5vl:7b. إذا كان لدى أكثر من موفر صور مكوّن المعرّف المجرد نفسه، فاستخدم بادئة الموفر صراحةً. قد تحتاج نماذج الرؤية المحلية البطيئة إلى مهلة أطول لفهم الصور من نماذج السحابة. كما يمكن أن تتعطل أو تتوقف عندما يحاول Ollama تخصيص سياق الرؤية الكامل المعلن عنه على عتاد محدود. عيّن مهلة للقدرة، وحدد سقفًا لـ num_ctx في إدخال النموذج عندما لا تحتاج إلا إلى دورة وصف صورة عادية: 
{
  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 }],
      },
    },
  },
}
تنطبق هذه المهلة على فهم الصور الواردة وعلى أداة image الصريحة التي يستطيع الوكيل استدعاءها أثناء دورة. لا يزال models.providers.ollama.timeoutSeconds على مستوى الموفر يتحكم في حارس طلب 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 يدويًا، فميّز نماذج الرؤية بدعم إدخال الصور: 
{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}
يرفض OpenClaw طلبات وصف الصور للنماذج غير المعلّمة كقادرة على الصور. مع الاكتشاف الضمني، يقرأ OpenClaw هذا من Ollama عندما يبلغ /api/show عن قدرة رؤية.

​
التكوين

أبسط مسار تمكين محلي فقط يكون عبر متغير بيئة:
export OLLAMA_API_KEY="ollama-local"
إذا كان OLLAMA_API_KEY معيّنًا، يمكنك حذف apiKey في إدخال الموفر وسيملؤه OpenClaw لفحوصات التوفر.

​
وصفات شائعة

استخدم هذه كنقاط بداية واستبدل معرفات النماذج بالأسماء الدقيقة من ollama list أو openclaw models list --provider ollama.
استخدم هذا عندما يعمل Ollama على الجهاز نفسه مثل Gateway وتريد أن يكتشف OpenClaw النماذج المثبتة تلقائيًا.
ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4
يبقي هذا المسار التكوين في الحد الأدنى. لا تضف كتلة models.providers.ollama إلا إذا كنت تريد تعريف النماذج يدويًا.
استخدم عناوين URL الأصلية لـ Ollama لمضيفي LAN. لا تضف /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 محلي أو على LAN مسجّل الدخول باستخدام ollama signin ويجب أن يخدم النماذج المحلية ونماذج :cloud معًا.
ollama signin
ollama 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: {
    defaults: {
      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 وأدوات الرسائل من سطح الوكيل، لكنه لا يغيّر سياق تشغيل Ollama أو وضع التفكير. اقرنه بـ params.num_ctx صريح وparams.thinking: false لنماذج التفكير الصغيرة بأسلوب Qwen التي تدخل في حلقات أو تستهلك ميزانية الاستجابة في الاستدلال المخفي.

​
اختيار النموذج

بعد الإعداد، تصبح كل نماذج Ollama لديك متاحة: 
{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}
تُدعم أيضًا معرّفات موفري Ollama المخصصة. عندما يستخدم مرجع نموذج بادئة الموفر النشط، مثل ollama-spark/qwen3:32b، يزيل OpenClaw تلك البادئة فقط قبل استدعاء Ollama كي يتلقى الخادم qwen3:32b. للنماذج المحلية البطيئة، فضّل ضبط الطلب على نطاق الموفر قبل رفع مهلة تشغيل الوكيل بالكامل: 
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
ينطبق timeoutSeconds على طلب HTTP للنموذج، بما في ذلك إعداد الاتصال، والترويسات، وبث الجسم، وإيقاف الجلب المحروس الإجمالي. يُمرَّر params.keep_alive إلى Ollama كـ keep_alive من المستوى الأعلى في طلبات /api/chat الأصلية؛ عيّنه لكل نموذج عندما يكون وقت تحميل الدور الأول هو عنق الزجاجة.

​
التحقق السريع

# Ollama daemon visible to this machine
curl http://127.0.0.1:11434/api/tags

# OpenClaw catalog and selected model
openclaw models list --provider ollama
openclaw models status

# Direct model smoke
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"
للمضيفين البعيدين، استبدل 127.0.0.1 بالمضيف المستخدم في baseUrl. إذا كان curl يعمل لكن OpenClaw لا يعمل، فتحقق مما إذا كان Gateway يعمل على جهاز أو حاوية أو حساب خدمة مختلف.

​
بحث Ollama على الويب

يدعم OpenClaw بحث Ollama على الويب كموفر web_search مضمّن.
الخاصيةالتفاصيل
المضيفيستخدم مضيف Ollama المُعدّ لديك (models.providers.ollama.baseUrl عند ضبطه، وإلا http://127.0.0.1:11434)؛ يستخدم https://ollama.com واجهة API المستضافة مباشرة
المصادقةبلا مفتاح لمضيفي Ollama المحليين المسجّل دخولهم؛ OLLAMA_API_KEY أو مصادقة الموفر المُعدّة للبحث المباشر عبر https://ollama.com أو المضيفين المحميين بالمصادقة
المتطلبيجب أن تكون المضيفات المحلية/ذاتية الاستضافة قيد التشغيل ومسجّلًا دخولها باستخدام ollama signin؛ يتطلب البحث المستضاف المباشر baseUrl: "https://ollama.com" بالإضافة إلى مفتاح Ollama API حقيقي
اختر بحث Ollama على الويب أثناء openclaw onboard أو openclaw configure --section web، أو اضبط: 
{
  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" },
    },
  },
}
بالنسبة إلى عفريت محلي مسجّل الدخول، يستخدم OpenClaw وكيل العفريت /api/experimental/web_search. وبالنسبة إلى https://ollama.com، يستدعي نقطة النهاية المستضافة /api/web_search مباشرة.
للحصول على تفاصيل الإعداد والسلوك الكاملة، راجع بحث Ollama على الويب.

​
الإعداد المتقدم

استدعاء الأدوات غير موثوق في الوضع المتوافق مع OpenAI. استخدم هذا الوضع فقط إذا كنت تحتاج إلى تنسيق OpenAI لوكيل وسيط ولا تعتمد على سلوك استدعاء الأدوات الأصلي.
إذا كنت تحتاج إلى استخدام نقطة النهاية المتوافقة مع 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 الأكبر من ملفات 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؛ يتم تجاهل القيم غير الصالحة، والصفرية، والسالبة، وغير المنتهية. ما زال محوّل 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 off
openclaw 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 الأساسي لـ Ollama ومفتاح API المُعدّين، ويستدعي نقطة نهاية Ollama الحالية /api/embed، ويجمع عدة أجزاء ذاكرة في طلب input واحد عندما يكون ذلك ممكنًا.
الخاصيةالقيمة
النموذج الافتراضي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 واجهة 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".
إذا كنت بحاجة إلى استخدام نقطة النهاية المتوافقة مع OpenAI، فراجع قسم “الوضع القديم المتوافق مع OpenAI” أعلاه. قد لا يعمل البث واستدعاء الأدوات معًا في ذلك الوضع.

​
استكشاف الأخطاء وإصلاحها

على 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 بدلًا من حدث قاتل OOM في Linux
يسجل 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=5m
ollama 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 installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model
تحقق من أن Ollama يعمل على المنفذ الصحيح:
# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve
تحقق من الجهاز نفسه وبيئة التشغيل نفسها التي تشغّل Gateway:
openclaw gateway status --deep
curl http://ollama-host:11434/api/tags
الأسباب الشائعة:
  • يشير baseUrl إلى localhost، لكن Gateway يعمل في Docker أو على مضيف آخر.
  • يستخدم URL المسار /v1، ما يختار سلوكًا متوافقًا مع OpenAI بدلًا من Ollama الأصلي.
  • يحتاج المضيف البعيد إلى تغييرات في جدار الحماية أو ربط LAN من جهة Ollama.
  • النموذج موجود على خادم laptop لديك لكنه غير موجود على الخادم البعيد.
يعني هذا عادةً أن المزوّد يستخدم الوضع المتوافق مع 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" --json
openclaw 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 إذا استغرق التوليد وقتًا طويلًا جدًا.
مزيد من المساعدة: استكشاف الأخطاء وإصلاحها والأسئلة الشائعة.

​
ذات صلة

Model providers

نظرة عامة على جميع المزوّدين ومراجع النماذج وسلوك تجاوز الفشل.

Model selection

كيفية اختيار النماذج وتكوينها.

Ollama Web Search

تفاصيل الإعداد والسلوك الكاملة للبحث على الويب المدعوم من Ollama.

Configuration

مرجع التكوين الكامل.