设置
认证规则¶
本地与局域网主机
回环地址、专用网络、.local 以及裸主机名形式的 Ollama URL 不需要真实 bearer token。OpenClaw 会为这些情况使用 ollama-local 标记。
远程主机与 Ollama Cloud 主机
公共远程主机以及 https://ollama.com 需要真实凭据:OLLAMA_API_KEY、认证配置文件(auth profile)或提供者的 apiKey。对于直接托管使用,优先选择 ollama-cloud 提供者。
自定义提供者 ID
带有 api: "ollama" 的自定义提供者遵循相同规则。例如,指向私有局域网主机的 ollama-remote 提供者可以使用 apiKey: "ollama-local";子代理会通过 Ollama 提供者钩子解析该标记,而不会将其视为缺失的凭据。memory.search.provider 也可以指向某个自定义提供者 ID,以便嵌入使用该 Ollama 端点。
认证配置文件
SQLite 认证存储中保存着某个提供者 ID 的凭据;将端点设置(baseUrl、api、模型、请求头、超时)放在 models.providers.<id> 中。较旧的扁平 auth-profiles.json 文件(例如 { "ollama-windows": { "apiKey": "ollama-local" } })不是运行时格式;openclaw doctor --fix 会将其导入 SQLite,作为规范的 ollama-windows:default API 密钥配置文件,并附带备份。该旧文件中的 baseUrl 值是无意义的,应移到提供者配置中。
记忆嵌入适用范围
Ollama 记忆嵌入的 Bearer 认证仅作用于为其声明的那个主机:
- 提供者级别的密钥只会发送到该提供者的主机。
memory.search.remote.apiKey和每个代理的覆盖项只会发送到它们的远程嵌入主机。- 纯
OLLAMA_API_KEY环境变量值被视为 Ollama Cloud 约定,默认不会发送到本地/自托管主机。
开始使用¶
1. 运行引导设置
选择 Ollama,然后选择模式:Cloud + Local 或 Local only。对于没有本地 Ollama 主机的托管模型,请改为选择 Ollama Cloud。
在全新的引导式设置中,OpenClaw 首先检查默认或配置的 Ollama 主机。自动发现仅考虑已加载到内存中的模型(由 /api/ps 报告),并需通过 /api/show 确认支持工具且至少具有 16K 上下文。已安装到磁盘但未加载的符合条件的模型不会成为自动候选。所选路由仍需要一次真实补全,OpenClaw 才会保存它;自动发现绝不会拉取或加载空闲模型。
若要在桌面 Model Setup 中使用已安装但空闲的模型,请点击 Ollama 卡片上的 Choose connection(选择连接),然后选择 Local only(仅本地)。此显式设置路径可以在不要求模型已加载的情况下,为实时检查准备一个符合条件的已安装模型。
2. 选择模型
Cloud + Local 和 Local only 会提示输入 Ollama 基础 URL,并检查已安装的模型;ollama.com URL 在这些模式中会被拒绝,因为托管访问属于 Ollama Cloud。如果找不到支持工具调用的模型,设置流程可以请求允许拉取推荐模型。已安装的 :latest 标签(如 gemma4:latest)只显示一次,而不会与 gemma4 重复列出。Cloud + Local 还会检查该主机是否已登录以进行云访问。
3. 验证
非交互模式:
openclaw onboard --non-interactive --accept-risk --skip-health \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b"
--custom-base-url 和 --custom-model-id 是可选的。省略基础 URL 时使用本地默认主机。未提供模型 ID 时,设置流程会优先选择已安装且支持工具调用、至少具备 16K 上下文的模型,并偏好非推理模型,然后是较小模型。如果没有符合条件的模型,则尝试建议的 gemma4 模型。
仅声明为嵌入用途的本地模型不能选作聊天默认模型。设置流程会报告错误并保持现有配置不变;重置预检也会拒绝显式选定的仅嵌入模型,或完全声明为仅嵌入用途的模型清单。同时支持补全和嵌入的模型仍然符合条件。
已配置的嵌入行不会被删除。请将它们从 models.providers.ollama.models 中移除,或重新运行 Ollama 引导设置以重建列表。重新引导会替换该提供者的模型目录,因此在运行之前请保留任何你想保留的自定义模型条目。
1. 安装并启动 Ollama
从 ollama.com/download 获取,然后拉取一个模型:
如需混合云访问,请在同一个主机上运行 ollama signin。
2. 设置凭据
对于本地或局域网主机,任何值都可用:
对于 https://ollama.com,请改用真实密钥:
或在配置中:openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"。
3. 选择模型
或在配置中:
通过本地主机使用云模型¶
Cloud + Local 通过一个可访问的 Ollama 主机同时路由本地模型和 :cloud 模型——这是 Ollama 的混合流程,也是你在设置中同时需要两者时应选的模式。
OpenClaw 会提示输入基础 URL,发现本地模型,并检查 ollama signin 状态。如果已登录,它会建议托管的默认模型(minimax-m2.7:cloud、minimax-m3:cloud、kimi-k3:cloud、glm-5.1:cloud、glm-5.2:cloud)。如果未登录,设置流程将保持仅本地模式,直到你运行 ollama signin。
对于仅通过云端访问且没有本地守护进程的情况,请使用 openclaw onboard --auth-choice ollama-cloud,并参阅 Ollama Cloud —— 该路径不需要 ollama signin 或运行中的服务器:
Ollama Cloud 模型列表来自使用你的密钥进行的实时 https://ollama.com/api/tags 发现,因此选择器会反映当前的托管目录。如果没有可用的密钥,OpenClaw 会显示其内置的 Ollama Cloud 目录。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw