设置

认证规则¶

本地和 LAN 主机

回环地址、私有网络、.local 和裸主机名形式的 Ollama URL 不需要真实的 bearer token。OpenClaw 对它们使用 ollama-local 标记。

远程和 Ollama Cloud 主机

公共远程主机和 https://ollama.com 需要真实凭据：OLLAMA_API_KEY、认证配置文件或提供方的 apiKey。对于直接使用托管服务的情况，优先选择 ollama-cloud 提供方。

自定义提供方 ID

带有 api: "ollama" 的自定义提供方遵循相同的规则。例如，指向私有 LAN 主机的 ollama-remote 提供方可以使用 apiKey: "ollama-local"；子代理会通过 Ollama provider hook 解析该标记，而不是将其视为缺失的凭据。memory.search.provider 也可以指向自定义提供方 ID，以便 embeddings 使用该 Ollama 端点。

认证配置文件

SQLite 认证存储按提供方 ID 保存凭据；将端点设置（baseUrl、api、models、headers、timeouts）放在 models.providers.<id> 中。旧式的扁平 auth-profiles.json 文件（如 { "ollama-windows": { "apiKey": "ollama-local" } }）不是运行时格式；openclaw doctor --fix 会将它们作为带有备份的规范 ollama-windows:default API-key 配置文件导入 SQLite。该旧文件中的 baseUrl 值是噪音，应移到提供方配置中。

记忆 embedding 作用域

Ollama 记忆 embeddings 的 Bearer 认证范围限定在声明它的主机上：

提供方级别的密钥只会发送到该提供方的主机。
memory.search.remote.apiKey 和按代理的覆盖设置只会发送到各自的远程 embedding 主机。
纯 OLLAMA_API_KEY 环境变量值会被视为 Ollama Cloud 约定，默认不会发送到本地/自托管主机。

入门指南¶

引导式设置（推荐）手动设置

1. 运行引导设置

openclaw onboard

选择 Ollama，然后选择一种模式：Cloud + Local、Cloud only 或 Local only。

在全新的引导式设置中，OpenClaw 会首先检查默认或已配置的 Ollama 主机。自动发现只考虑已加载到内存中的模型（由 /api/ps 报告），并需要通过 /api/show 确认支持工具调用且上下文至少为 16K。已安装到磁盘但未加载的合格模型不会成为自动候选。所选路由仍然需要一次真实的补全，OpenClaw 才会保存它；发现过程绝不会拉取或加载闲置模型。

要在桌面版 Model Setup 中使用已安装但闲置的模型，请在 Ollama 卡片上选择 Choose connection，然后选择 Local only。这种显式设置路径可以为实时检查准备合格的已安装模型，而无需它已处于加载状态。

2. 选择模型

Cloud only 会提示输入 OLLAMA_API_KEY，并建议托管的云默认模型。Cloud + Local 和 Local only 会提示输入 Ollama 基础 URL，并检查已安装的模型。如果没有找到支持工具的模型，设置过程会请求许可来拉取推荐模型。已安装的 :latest 标签（如 gemma4:latest）只会显示一次，而不会重复显示为 gemma4。Cloud + Local 还会检查主机是否已登录以进行云访问。

3. 验证

openclaw models list --provider ollama

非交互式：

```bash
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` 是可选的；省略它们将使用本地默认主机和建议的 `gemma4` 模型。

被标记为仅支持 embedding 的本地模型不能选作聊天默认模型。设置过程会报告错误并保持现有配置不变；重置预检同样会拒绝显式选择的仅 embedding 模型，或完全仅 embedding 的模型清单。同时支持补全和 embeddings 的模型仍然符合条件。

1. 安装并启动 Ollama

从 ollama.com/download 获取，然后拉取一个模型：

ollama pull gemma4

要进行混合云访问，请在同一个主机上运行 ollama signin。

2. 设置凭据

对于本地或局域网主机，任何值都有效：

export OLLAMA_API_KEY="ollama-local"

对于 https://ollama.com，请改用真实的密钥：

export OLLAMA_API_KEY="your-real-key"

或者在配置中：openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"。

3. 选择模型

openclaw models list
openclaw models set ollama/gemma4

或者在配置中：

{
  agents: {
    defaults: {
      model: { primary: "ollama/gemma4" },
    },
  },
}

通过本地主机使用云模型¶

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 或正在运行的服务器：

openclaw onboard --auth-choice ollama-cloud
openclaw models set ollama-cloud/minimax-m2.7:cloud

openclaw onboard 期间显示的云模型列表会实时从 https://ollama.com/api/tags 获取，上限为 500 条，因此选择器反映的是当前的托管目录。如果在设置时 ollama.com 不可达或返回的模型列表为空，OpenClaw 会回退到其硬编码的建议列表，从而保证引导过程仍然可以完成。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw