Ollama

Các URL Ollama dùng local loopback, mạng riêng, .local và tên máy chủ thuần túy không cần mã thông báo bearer thực. OpenClaw sử dụng dấu hiệu ollama-local cho các URL này.

Các máy chủ từ xa công khai và https://ollama.com yêu cầu thông tin xác thực thực: OLLAMA_API_KEY, hồ sơ xác thực hoặc apiKey của nhà cung cấp. Để sử dụng trực tiếp dịch vụ lưu trữ, nên dùng nhà cung cấp ollama-cloud.

Nhà cung cấp tùy chỉnh có api: "ollama" tuân theo cùng các quy tắc. Ví dụ: nhà cung cấp ollama-remote trỏ đến máy chủ LAN riêng có thể sử dụng apiKey: "ollama-local"; các tác nhân phụ phân giải dấu hiệu đó thông qua hook của nhà cung cấp Ollama thay vì coi đó là thông tin xác thực bị thiếu. agents.defaults.memorySearch.provider cũng có thể trỏ đến mã nhà cung cấp tùy chỉnh để các embedding sử dụng điểm cuối Ollama đó.

auth-profiles.json lưu trữ thông tin xác thực cho một mã nhà cung cấp; hãy đặt các thiết lập điểm cuối (baseUrl, api, mô hình, tiêu đề, thời gian chờ) trong models.providers.<id>. Các tệp phẳng cũ như { "ollama-windows": { "apiKey": "ollama-local" } } không phải là định dạng thời gian chạy; openclaw doctor --fix ghi lại chúng thành hồ sơ khóa API chuẩn ollama-windows:default kèm bản sao lưu. Giá trị baseUrl trong tệp cũ đó là dữ liệu thừa và nên được chuyển sang cấu hình nhà cung cấp.

Xác thực bearer cho embedding bộ nhớ Ollama được giới hạn trong máy chủ mà xác thực đó được khai báo:

• Khóa cấp nhà cung cấp chỉ được gửi đến máy chủ của nhà cung cấp đó.
• agents.*.memorySearch.remote.apiKey chỉ được gửi đến máy chủ embedding từ xa tương ứng.
• Giá trị biến môi trường OLLAMA_API_KEY độc lập được coi là quy ước của Ollama Cloud và theo mặc định không được gửi đến các máy chủ cục bộ/tự lưu trữ.

Ollama trên cùng máy với Gateway, được tự động phát hiện:

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

Không thêm khối models.providers.ollama trừ khi bạn cần các mô hình thủ công.

{  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 là ngân sách ngữ cảnh của OpenClaw; params.num_ctx được gửi đến Ollama. Hãy giữ chúng đồng bộ khi phần cứng không thể chạy toàn bộ ngữ cảnh mà mô hình công bố.

Không có trình nền cục bộ, dùng trực tiếp các mô hình được lưu trữ:

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" },    },  },}

Để dùng mã định danh nhà cung cấp chuyên biệt ollama-cloud thay cho cấu trúc này, hãy xem Ollama Cloud.

Dùng ID nhà cung cấp tùy chỉnh khi chạy nhiều máy chủ Ollama; mỗi máy chủ có máy chủ lưu trữ, mô hình, thông tin xác thực và thời gian chờ riêng.

{  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 loại bỏ tiền tố nhà cung cấp đang hoạt động (nếu không có thì dùng tiền tố thuần ollama/) trước khi gọi Ollama, vì vậy ollama-large/qwen3.5:27b được gửi đến Ollama dưới dạng qwen3.5:27b.

Một số mô hình cục bộ xử lý tốt các lời nhắc đơn giản nhưng gặp khó khăn với toàn bộ bề mặt công cụ của tác tử. Hãy giới hạn công cụ và ngữ cảnh trước khi thay đổi các thiết lập thời gian chạy toàn cục:

{  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 },          },        ],      },    },  },}

Chỉ dùng compat.supportsTools: false khi mô hình hoặc máy chủ thường xuyên gặp lỗi với lược đồ công cụ — tùy chọn này đánh đổi khả năng của tác tử để lấy tính ổn định. localModelLean loại bỏ các công cụ nặng về trình duyệt, cron, tin nhắn, tạo phương tiện, giọng nói và PDF khỏi bề mặt trực tiếp của tác tử trừ khi được yêu cầu rõ ràng, đồng thời đặt các danh mục lớn hơn phía sau Tìm kiếm công cụ. Tùy chọn này không thay đổi ngữ cảnh thời gian chạy hoặc chế độ suy nghĩ của Ollama. Hãy kết hợp với params.num_ctx và params.thinking: false cho các mô hình suy nghĩ nhỏ kiểu Qwen thường lặp vòng hoặc tiêu tốn ngân sách vào suy luận ẩn.

Đặt rõ api: "openai-completions" cho proxy phía sau /v1/chat/completions:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: true, // mặc định: true        apiKey: "ollama-local",        models: [...]      }    }  }}

Chế độ này có thể không hỗ trợ đồng thời truyền trực tuyến và gọi công cụ; bạn có thể cần đặt params: { streaming: false } trên mô hình.

Theo mặc định, OpenClaw chèn options.num_ctx trong chế độ này để Ollama không âm thầm quay về ngữ cảnh 4096 token. Nếu proxy của bạn từ chối các trường options không xác định, hãy tắt tính năng này:

{  models: {    providers: {      ollama: {        baseUrl: "http://ollama-host:11434/v1",        api: "openai-completions",        injectNumCtxForOpenAICompat: false,        apiKey: "ollama-local",        models: [...]      }    }  }}

Đối với các mô hình được tự động phát hiện, OpenClaw sử dụng cửa sổ ngữ cảnh do /api/show báo cáo, bao gồm các giá trị PARAMETER num_ctx lớn hơn từ Modelfile tùy chỉnh; nếu không, hệ thống quay về cửa sổ ngữ cảnh Ollama mặc định của OpenClaw.

contextWindow, contextTokens và maxTokens ở cấp nhà cung cấp đặt giá trị mặc định cho mọi mô hình thuộc nhà cung cấp đó và có thể được ghi đè theo từng mô hình. contextWindow là ngân sách lời nhắc/Compaction riêng của OpenClaw. Các yêu cầu /api/chat gốc không đặt options.num_ctx trừ khi bạn đặt rõ params.num_ctx, vì vậy Ollama áp dụng giá trị mặc định của chính mô hình, OLLAMA_CONTEXT_LENGTH hoặc giá trị dựa trên VRAM; các giá trị params.num_ctx không hợp lệ, bằng không, âm hoặc không hữu hạn sẽ bị bỏ qua. Nếu một cấu hình cũ chỉ dùng contextWindow/maxTokens để ép ngữ cảnh yêu cầu gốc, hãy chạy openclaw doctor --fix để sao chép các giá trị đó vào params.num_ctx. Bộ điều hợp tương thích OpenAI vẫn mặc định chèn options.num_ctx từ params.num_ctx hoặc contextWindow đã cấu hình; hãy tắt bằng injectNumCtxForOpenAICompat: false nếu hệ thống thượng nguồn từ chối options.

Các mục mô hình gốc cũng chấp nhận các tùy chọn thời gian chạy Ollama phổ biến trong params, được chuyển tiếp dưới dạng options của /api/chat gốc: 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 và num_thread. Một số khóa (format, keep_alive, truncate, shift) được chuyển tiếp dưới dạng trường yêu cầu cấp cao nhất thay vì nằm trong options. OpenClaw chỉ chuyển tiếp các khóa yêu cầu Ollama này, vì vậy các tham số chỉ dành cho thời gian chạy như streaming không bao giờ được gửi đến Ollama. Dùng params.think (hoặc params.thinking) để đặt think cấp cao nhất; false tắt chức năng suy nghĩ ở cấp API cho các mô hình suy nghĩ kiểu 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 theo từng mô hình cũng hoạt động; mục mô hình nhà cung cấp được khai báo rõ sẽ được ưu tiên nếu cả hai đều được đặt.

OpenClaw chuyển tiếp chế độ suy nghĩ theo cách Ollama yêu cầu: think cấp cao nhất, không phải options.think. Các mô hình được tự động phát hiện mà /api/show báo cáo có khả năng thinking sẽ cung cấp /think low, /think medium, /think high và /think max; các mô hình không có khả năng suy nghĩ chỉ cung cấp /think off.

openclaw agent --model ollama/gemma4 --thinking offopenclaw agent --model ollama/gemma4 --thinking low

Hoặc đặt giá trị mặc định cho mô hình:

{  agents: {    defaults: {      models: {        "ollama/gemma4": {          thinking: "low",        },      },    },  },}

params.think/params.thinking theo từng mô hình có thể tắt hoặc buộc API sử dụng chế độ suy luận cho một mô hình cụ thể. OpenClaw giữ nguyên cấu hình tường minh đó khi lượt chạy hiện tại chỉ có giá trị mặc định ngầm định off; một lệnh thời gian chạy khác off, chẳng hạn /think medium, vẫn ghi đè cấu hình này. Yêu cầu suy luận có giá trị đúng không bao giờ được gửi đến mô hình được đánh dấu rõ ràng là reasoning: false; yêu cầu think: false luôn được gửi bất kể trường hợp nào.

Các mô hình có tên deepseek-r1, reasoning, reason hoặc think mặc định được xem là có khả năng suy luận — không cần cấu hình bổ sung:

ollama pull deepseek-r1:32b

Ollama chạy cục bộ và miễn phí, vì vậy mọi chi phí mô hình đều là 0 cho cả mô hình được tự động phát hiện và mô hình được định nghĩa thủ công.

Plugin Ollama đi kèm đăng ký một nhà cung cấp embedding bộ nhớ cho tìm kiếm bộ nhớ. Plugin sử dụng URL cơ sở và khóa API Ollama đã cấu hình, gọi /api/embed, đồng thời gộp nhiều đoạn bộ nhớ vào một yêu cầu input khi có thể.

Khi proxy.enabled=true, các yêu cầu embedding đến chính xác origin local loopback của máy chủ được suy ra từ baseUrl đã cấu hình sẽ sử dụng đường dẫn trực tiếp có bảo vệ của OpenClaw thay vì proxy chuyển tiếp được quản lý. Bản thân tên máy chủ đã cấu hình phải là localhost hoặc một địa chỉ IP loopback dạng chữ — các tên DNS chỉ phân giải thành loopback vẫn sử dụng đường dẫn proxy được quản lý. Các máy chủ Ollama trên LAN, tailnet, mạng riêng và mạng công cộng luôn sử dụng đường dẫn proxy được quản lý; các lượt chuyển hướng đến máy chủ/cổng khác không kế thừa độ tin cậy. proxy.loopbackMode: "proxy" vẫn định tuyến lưu lượng loopback qua proxy; proxy.loopbackMode: "block" từ chối lưu lượng này trước khi kết nối — xem Proxy được quản lý.

Các embedding tại thời điểm truy vấn sử dụng tiền tố truy xuất đối với những mô hình yêu cầu hoặc khuyến nghị chúng: nomic-embed-text, qwen3-embedding và mxbai-embed-large. Các lô tài liệu vẫn giữ nguyên dữ liệu thô, vì vậy các chỉ mục hiện có không cần di chuyển định dạng.

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        remote: {          // Mặc định cho Ollama. Tăng trên các máy chủ lớn hơn nếu việc lập lại chỉ mục quá chậm.          nonBatchConcurrency: 1,        },      },    },  },}

Đối với máy chủ embedding từ xa, chỉ cấp phạm vi xác thực cho máy chủ đó:

{  agents: {    defaults: {      memorySearch: {        provider: "ollama",        model: "nomic-embed-text",        remote: {          baseUrl: "http://gpu-box.local:11434",          apiKey: "ollama-local",          nonBatchConcurrency: 2,        },      },    },  },}

Ollama mặc định sử dụng API gốc (/api/chat), hỗ trợ đồng thời truyền trực tiếp và gọi công cụ — không cần cấu hình đặc biệt.

Đối với yêu cầu gốc, điều khiển suy luận được chuyển tiếp trực tiếp: /think off và openclaw agent --thinking off gửi think: false ở cấp cao nhất, trừ khi params.think/params.thinking được cấu hình tường minh; /think low|medium|high gửi chuỗi mức độ tương ứng; /think max ánh xạ thành mức độ cao nhất của Ollama, think: "high".

Trên WSL2 với NVIDIA/CUDA, trình cài đặt Ollama Linux chính thức tạo một đơn vị systemd ollama.service với Restart=always. Nếu dịch vụ đó tự động khởi động và tải một mô hình dùng GPU trong quá trình WSL2 khởi động, Ollama có thể ghim bộ nhớ máy chủ trong lúc tải; cơ chế thu hồi bộ nhớ của Hyper-V không phải lúc nào cũng thu hồi được các trang đó, nên Windows có thể chấm dứt máy ảo WSL2, systemd khởi động lại Ollama và vòng lặp tiếp diễn.

Dấu hiệu: WSL2 liên tục khởi động lại/bị chấm dứt, mức sử dụng CPU cao trong app.slice hoặc ollama.service ngay sau khi WSL2 khởi động, và SIGTERM từ systemd thay vì trình xử lý hết bộ nhớ của Linux.

OpenClaw ghi cảnh báo khi khởi động nếu phát hiện WSL2, ollama.service được bật với Restart=always và có các dấu hiệu CUDA hiển thị.

Cách giảm thiểu:

sudo systemctl disable ollama

Ở phía Windows, thêm nội dung này vào %USERPROFILE%\.wslconfig, rồi chạy wsl --shutdown:

[experimental]autoMemoryReclaim=disabled

Hoặc rút ngắn thời gian duy trì hoạt động / chỉ khởi động Ollama thủ công khi cần:

export OLLAMA_KEEP_ALIVE=5mollama serve

Xem ollama/ollama#11317.

Xác nhận Ollama đang chạy, OLLAMA_API_KEY (hoặc một hồ sơ xác thực) đã được thiết lập và models.providers.ollama không được định nghĩa tường minh:

ollama servecurl http://localhost:11434/api/tags

Tải mô hình xuống cục bộ hoặc định nghĩa mô hình đó một cách tường minh trong models.providers.ollama:

ollama list  # Xem những gì đã được cài đặtollama pull gemma4ollama pull gpt-oss:20bollama pull llama3.3     # Hoặc một mô hình khác

Xác minh từ cùng máy và môi trường thời gian chạy đang chạy Gateway:

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

Các nguyên nhân phổ biến:

• baseUrl trỏ đến localhost, nhưng Gateway chạy trong Docker hoặc trên một máy chủ khác.
• URL sử dụng /v1, chọn hành vi tương thích OpenAI thay vì Ollama gốc.
• Máy chủ từ xa cần thay đổi tường lửa hoặc liên kết LAN.
• Mô hình nằm trên daemon của máy tính xách tay nhưng không có trên daemon từ xa.

Thông thường, nhà cung cấp đang ở chế độ tương thích OpenAI hoặc mô hình không thể xử lý lược đồ công cụ. Nên ưu tiên chế độ gốc:

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

Nếu một mô hình cục bộ nhỏ vẫn không xử lý được lược đồ công cụ, hãy đặt compat.supportsTools: false cho mục mô hình đó và kiểm tra lại.

Các phản hồi Kimi/GLM được lưu trữ có những chuỗi ký hiệu dài, không mang tính ngôn ngữ sẽ được xử lý như một lệnh gọi nhà cung cấp thất bại thay vì một phản hồi thành công, để cơ chế thử lại/chuyển đổi dự phòng/xử lý lỗi thông thường tiếp quản thay vì lưu văn bản hỏng vào phiên.

Nếu sự cố tái diễn, hãy ghi lại tên mô hình, tệp phiên hiện tại và lượt chạy đã sử dụng Cloud + Local hay Cloud only, sau đó thử một phiên mới và một mô hình dự phòng:

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

Các mô hình cục bộ lớn có thể cần nhiều thời gian cho lần tải đầu tiên. Hãy giới hạn phạm vi thời gian chờ cho nhà cung cấp Ollama và tùy chọn giữ mô hình ở trạng thái đã tải giữa các lượt:

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

Nếu bản thân máy chủ phản hồi kết nối chậm, timeoutSeconds cũng kéo dài thời gian chờ kết nối có bảo vệ cho nhà cung cấp này.

Nhiều mô hình công bố kích thước ngữ cảnh lớn hơn mức phần cứng của bạn có thể vận hành thoải mái. Ollama gốc sử dụng giá trị mặc định của môi trường thời gian chạy riêng, trừ khi params.num_ctx được đặt. Hãy giới hạn cả ngân sách của OpenClaw và ngữ cảnh yêu cầu của Ollama để có độ trễ đến token đầu tiên ổn định:

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

Giảm contextWindow nếu OpenClaw gửi quá nhiều prompt. Giảm params.num_ctx nếu ngữ cảnh thời gian chạy của Ollama quá lớn đối với máy. Giảm maxTokens nếu quá trình tạo nội dung kéo dài quá lâu.