Ollama

Các URL Ollama dạng loopback, mạng riêng, .local và tên máy chủ trần không cần bearer token thực. OpenClaw sử dụng dấu mốc ollama-local cho các trường hợp 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, một 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ụ được 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 tử con phân giải dấu mốc đó thông qua hook 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ột id nhà cung cấp tùy chỉnh để các embedding sử dụng endpoint Ollama đó.

auth-profiles.json lưu trữ thông tin xác thực cho một id nhà cung cấp; đặt các thiết lập endpoint (baseUrl, api, mô hình, header, 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 một hồ sơ khóa API ollama-windows:default chuẩn kèm bản sao lưu. Giá trị baseUrl trong tệp cũ đó là dữ liệu nhiễu 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à nó đượ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 của nó.
• Giá trị env OLLAMA_API_KEY thuần túy được coi là quy ước 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 phát hiện tự động:

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 được mô hình quảng bá.

Không có daemon cục bộ, sử 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" },    },  },}

Để sử dụng id nhà cung cấp chuyên biệt ollama-cloud thay cho cấu trúc này, hãy xem Ollama Cloud.

Sử dụng các ID nhà cung cấp tùy chỉnh khi chạy nhiều máy chủ Ollama; mỗi máy chủ có host, 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ố trần ollama/) trước khi gọi Ollama, vì vậy ollama-large/qwen3.5:27b đến Ollama dưới dạng qwen3.5:27b.

Một số mô hình cục bộ xử lý tốt các prompt đơn giản nhưng gặp khó khăn với toàn bộ bề mặt công cụ của agent. Hãy giới hạn công cụ và ngữ cảnh trước khi thay đổi các cài đặt runtime 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ỉ sử dụng compat.supportsTools: false khi mô hình hoặc máy chủ thường xuyên gặp lỗi với schema công cụ — tùy chọn này đánh đổi khả năng của agent để lấy sự ổn định. localModelLean loại bỏ các công cụ nặng về trình duyệt, cron, tin nhắn, tạo nội dung đa phương tiện, giọng nói và PDF khỏi bề mặt trực tiếp của agent 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 runtime 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ô hạn hoặc tiêu tốn ngân sách vào quá trình suy luận ẩn.

Đặt api: "openai-completions" một cách rõ ràng 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 luồng và gọi công cụ; bạn có thể cần params: { streaming: false } trên mô hình.

OpenClaw mặc định 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 từ chối các trường options không xác định, hãy tắt tùy chọn 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 mà /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, OpenClaw sẽ dùng cửa sổ ngữ cảnh Ollama mặc định của mình.

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 prompt/Compaction riêng của OpenClaw. Các yêu cầu /api/chat gốc để options.num_ctx ở trạng thái chưa đặt trừ khi bạn đặt params.num_ctx một cách rõ ràng, vì vậy Ollama áp dụng giá trị mặc định dựa trên mô hình, OLLAMA_CONTEXT_LENGTH hoặc VRAM của chính nó; 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ỉ sử dụng contextWindow/maxTokens để buộc 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ộ chuyển đổi 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 upstream 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 runtime Ollama phổ biến trong params, được chuyển tiếp dưới dạng /api/chat options 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 các 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 runtime như streaming không bao giờ được gửi đến Ollama. Sử dụng params.think (hoặc params.thinking) để đặt think cấp cao nhất; false tắt chế độ 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 chỉ định rõ sẽ được ưu tiên nếu cả hai đều được thiết lập.

OpenClaw chuyển tiếp chế độ suy luận theo cách Ollama mong đợi: 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 khả năng thinking sẽ cung cấp /think low, /think medium, /think high và /think max; các mô hình không suy luận 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 suy luận qua API cho một mô hình cụ thể. OpenClaw giữ nguyên cấu hình tường minh đó khi lượt chạy đang hoạt động chỉ có giá trị mặc định ngầm định off; một lệnh thời gian chạy không phải off như /think medium vẫn ghi đè lên cấu hình này. Yêu cầu suy luận có giá trị đúng sẽ 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ể cấu hình.

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

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 đối với 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 và 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 nguồn loopback cục bộ trên máy đượ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ý. Tên máy đã 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 đi qua đường dẫn proxy được quản lý, đồng thời 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 đó trước khi kết nối — xem Proxy được quản lý.

Embedding tại thời điểm truy vấn sử dụng các tiền tố truy xuất cho 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, hãy giới hạn phạm vi xác thực ở 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 phát trực tuyến và gọi công cụ — không cần cấu hình đặc biệt.

Đối với các yêu cầu gốc, chế độ kiểm soát 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ạ tới mức độ cao nhất của Ollama là 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 sử dụng GPU trong lúc WSL2 khởi động, Ollama có thể giữ chặt bộ nhớ máy chủ khi tải; cơ chế thu hồi bộ nhớ của Hyper-V không phải lúc nào cũng có thể thu hồi các trang đó, vì vậy 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/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ý OOM của Linux.

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

Biện pháp giảm thiểu:

sudo systemctl disable ollama

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

[experimental]autoMemoryReclaim=disabled

Hoặc rút ngắn thời gian duy trì kết nối / 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 rõ ràng:

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

Tải mô hình về máy cục bộ hoặc định nghĩa rõ ràng mô hình đó 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 chạy Gateway:

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

Các nguyên nhân thường gặp:

• 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 với OpenAI thay vì Ollama gốc.
• Máy chủ từ xa cần thay đổi cấu hình 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 với OpenAI hoặc mô hình không thể xử lý lược đồ công cụ. Ư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 trong mục nhập của mô hình đó rồi kiểm thử lại.

Các phản hồi Kimi/GLM được lưu trữ trên máy chủ chứa chuỗi ký hiệu dài, không mang tính ngôn ngữ được coi là 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, nhờ đó cơ chế thử lại/chuyển đổi dự phòng/xử lý lỗi thông thường sẽ tiếp quản thay vì lưu văn bản bị 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à liệu lần chạy có sử dụng Cloud + Local hay Cloud only hay không, 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 "Chỉ trả lời chính xác: 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. Giới hạn phạm vi thời gian chờ cho nhà cung cấp Ollama và tùy chọn duy trì 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ó thể chạy ổn định. Ollama gốc sử dụng giá trị mặc định của môi trường chạy riêng trừ khi params.num_ctx được thiết lập. 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ễ 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 nội dung nhắc. Giảm params.num_ctx nếu ngữ cảnh môi trường 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.