Ollama

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

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