Ollama

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

میزبان‌های عمومی از راه دور و Ollama Cloud (https://ollama.com) به اعتبارنامه واقعی از طریق OLLAMA_API_KEY، یک نمایه احراز هویت، یا apiKey ارائه‌دهنده نیاز دارند.

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

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

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

• کلید سطح ارائه‌دهنده فقط به میزبان Ollama همان ارائه‌دهنده ارسال می‌شود.
• agents.*.memorySearch.remote.apiKey فقط به میزبان embedding از راه دور خودش ارسال می‌شود.
• مقدار env صرف 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 اضافه نکنید.

برای hostهای LAN از 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 بودجه‌ی context سمت OpenClaw است. params.num_ctx برای درخواست به Ollama ارسال می‌شود. وقتی سخت‌افزار شما نمی‌تواند context کامل اعلام‌شده‌ی مدل را اجرا کند، آن‌ها را هم‌راستا نگه دارید.

وقتی daemon محلی اجرا نمی‌کنید و مدل‌های 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" },
    },
  },
}

وقتی یک daemon محلی یا LAN Ollama با 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 دارید، از شناسه‌های ارائه‌دهنده‌ی سفارشی استفاده کنید. هر ارائه‌دهنده host، مدل‌ها، auth،‏ timeout و ارجاع‌های مدل خودش را می‌گیرد.

{
  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 به‌صورت qwen3.5:27b به Ollama برسد.

برخی مدل‌های محلی می‌توانند به promptهای ساده پاسخ دهند اما با سطح کامل ابزارهای عامل مشکل دارند. پیش از تغییر تنظیمات global runtime، ابتدا ابزارها و context را محدود کنید.

{
  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 یا حالت تفکر آن را تغییر نمی‌دهد. برای مدل‌های تفکر کوچک به سبک Qwen که در حلقه می‌افتند یا بودجهٔ پاسخ خود را صرف استدلال پنهان می‌کنند، آن را با params.num_ctx صریح و params.thinking: false همراه کنید.

اگر لازم است به‌جای آن از نقطهٔ پایانی سازگار با 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 بی‌صدا به پنجرهٔ زمینهٔ ۴۰۹۶ برنگردد. اگر پراکسی/بالادست شما فیلدهای ناشناختهٔ 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 را تنظیم کنید؛ مقادیر نامعتبر، صفر، منفی، و غیرمتناهی نادیده گرفته می‌شوند. آداپتور سازگار با OpenAI برای Ollama همچنان به‌طور پیش‌فرض options.num_ctx را از params.num_ctx یا contextWindow پیکربندی‌شده تزریق می‌کند؛ اگر بالادست شما options را رد می‌کند، آن را با injectNumCtxForOpenAICompat: false غیرفعال کنید.

ورودی‌های مدل بومی 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 نشت نمی‌کنند. برای ارسال think سطح بالای Ollama از 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 برای هر مدل نیز کار می‌کند. اگر هر دو پیکربندی شده باشند، ورودی صریح مدل ارائه‌دهنده بر پیش‌فرض عامل اولویت دارد.

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

OpenClaw مدل‌هایی با نام‌هایی مانند deepseek-r1، reasoning، یا think را به‌طور پیش‌فرض دارای قابلیت استدلال در نظر می‌گیرد.

ollama pull deepseek-r1:32b

هیچ پیکربندی اضافه‌ای لازم نیست. OpenClaw آن‌ها را به‌طور خودکار علامت‌گذاری می‌کند.

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

Plugin همراه Ollama یک ارائه‌دهندهٔ تعبیهٔ حافظه برای جست‌وجوی حافظه ثبت می‌کند. این ارائه‌دهنده از URL پایهٔ Ollama و کلید API پیکربندی‌شده استفاده می‌کند، نقطهٔ پایانی فعلی /api/embed در Ollama را فراخوانی می‌کند، و در صورت امکان چندین قطعهٔ حافظه را در یک درخواست 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 به‌طور پیش‌فرض از API بومی Ollama (/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، نصب‌کنندهٔ رسمی Linux برای Ollama یک واحد systemd با نام ollama.service و Restart=always ایجاد می‌کند. اگر آن سرویس به‌طور خودکار شروع شود و هنگام راه‌اندازی WSL2 یک مدل متکی به GPU را بارگذاری کند، Ollama می‌تواند هنگام بارگذاری مدل حافظهٔ میزبان را پین کند. بازپس‌گیری حافظهٔ Hyper-V همیشه نمی‌تواند آن صفحه‌های پین‌شده را بازپس بگیرد، بنابراین Windows می‌تواند VM مربوط به WSL2 را خاتمه دهد، systemd دوباره Ollama را شروع می‌کند، و حلقه تکرار می‌شود.

شواهد رایج:

• راه‌اندازی‌های مجدد یا خاتمه‌های تکراری WSL2 از سمت Windows
• CPU بالا در app.slice یا ollama.service کمی پس از شروع WSL2
• SIGTERM از systemd به‌جای رویداد OOM-killer در Linux

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

کاهش اثر:

sudo systemctl disable ollama

این را در سمت Windows به %USERPROFILE%\.wslconfig اضافه کنید، سپس 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

اگر مدل شما فهرست نشده است، یا مدل را به‌صورت محلی pull کنید یا آن را صریحاً در 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

از همان ماشین و runtime که Gateway را اجرا می‌کند بررسی کنید:

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

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

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

این معمولاً یعنی provider از حالت سازگار با OpenAI استفاده می‌کند یا مدل نمی‌تواند schemaهای ابزار را مدیریت کند.

حالت بومی Ollama را ترجیح دهید:

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

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

پاسخ‌های میزبانی‌شدهٔ Kimi/GLM که طولانی و شامل اجراهای نمادی غیرزبانی هستند، به‌جای پاسخ موفق assistant، به‌عنوان خروجی ناموفق provider در نظر گرفته می‌شوند. این باعث می‌شود تلاش دوباره، fallback، یا مدیریت خطای عادی بدون ماندگار کردن متن خراب در session وارد عمل شود.

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

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

مدل‌های محلی بزرگ می‌توانند پیش از شروع جریان‌دهی به بارگذاری اولیهٔ طولانی نیاز داشته باشند. timeout را محدود به provider مربوط به Ollama نگه دارید، و به‌صورت اختیاری از Ollama بخواهید مدل را بین نوبت‌ها بارگذاری‌شده نگه دارد:

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

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

بسیاری از مدل‌های Ollama contextهایی را اعلام می‌کنند که بزرگ‌تر از آن‌اند که سخت‌افزار شما بتواند با آسودگی اجرا کند. Ollama بومی از پیش‌فرض context مربوط به runtime خود Ollama استفاده می‌کند، مگر اینکه params.num_ctx را تنظیم کنید. وقتی latency قابل‌پیش‌بینی برای توکن اول می‌خواهید، هم بودجهٔ OpenClaw و هم context درخواست Ollama را محدود کنید:

{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}

اگر OpenClaw prompt بیش از حدی ارسال می‌کند، ابتدا contextWindow را کاهش دهید. اگر Ollama یک context مربوط به runtime را بارگذاری می‌کند که برای ماشین بیش از حد بزرگ است، params.num_ctx را کاهش دهید. اگر تولید بیش از حد طول می‌کشد، maxTokens را کاهش دهید.