Ollama

本地和 LAN Ollama 主机不需要真实的 bearer token。OpenClaw 仅对 loopback、私有网络、.local 和裸主机名 Ollama base URL 使用本地 ollama-local 标记。

远程公共主机和 Ollama Cloud（https://ollama.com）需要通过 OLLAMA_API_KEY、凭证配置档或 provider 的 apiKey 提供真实凭证。

设置了 api: "ollama" 的自定义 provider id 遵循相同规则。例如，指向私有 LAN Ollama 主机的 ollama-remote provider 可以使用 apiKey: "ollama-local"，子智能体会通过 Ollama provider 钩子解析该标记，而不是将其视为缺失凭证。记忆搜索也可以将 agents.defaults.memorySearch.provider 设置为该自定义 provider id，以便嵌入使用匹配的 Ollama 端点。

auth-profiles.json 存储 provider id 的凭证。将端点设置（baseUrl、api、model id、headers、timeouts）放在 models.providers.<id> 中。较旧的扁平凭证配置档文件，例如 { "ollama-windows": { "apiKey": "ollama-local" } }，不是运行时格式；运行 openclaw doctor --fix 可将其重写为规范的 ollama-windows:default API-key 配置档并创建备份。该文件中的 baseUrl 是兼容性噪音，应移到 provider 配置中。

当 Ollama 用于记忆嵌入时，bearer 身份验证的作用域限定为声明它的主机：

• provider 级密钥只会发送到该 provider 的 Ollama 主机。
• agents.*.memorySearch.remote.apiKey 只会发送到其远程嵌入主机。
• 纯 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 块。

对于 LAN 主机，请使用原生 Ollama URL。不要添加 /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 是 OpenClaw 侧的上下文预算。params.num_ctx 会随请求发送给 Ollama。当你的硬件无法运行模型完整声明的上下文时，请保持二者一致。

当你不运行本地守护进程并希望直接使用托管的 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" },
    },
  },
}

当本地或 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 服务器时，请使用自定义提供商 ID。每个提供商都有自己的主机、模型、认证、超时和模型引用。

{
  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。

有些本地模型可以回答简单提示词，但难以处理完整的智能体工具表面。请先限制工具和上下文，再更改全局运行时设置。

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

仅当模型或服务器在工具 schema 上会可靠失败时，才使用 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 } 禁用流式传输。

当 Ollama 使用 api: "openai-completions" 时，OpenClaw 默认会注入 options.num_ctx，这样 Ollama 就不会静默回退到 4096 上下文窗口。如果你的代理/上游拒绝未知的 options 字段，请禁用此行为：

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

对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，包括来自自定义 Modelfile 的更大 PARAMETER num_ctx 值。否则，它会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。

你可以为该 Ollama 提供商下的每个模型设置提供商级别的 contextWindow、contextTokens 和 maxTokens 默认值，然后在需要时按模型覆盖它们。contextWindow 是 OpenClaw 的提示词和压缩预算。原生 Ollama 请求会保持 options.num_ctx 未设置，除非你显式配置 params.num_ctx，因此 Ollama 可以应用自己的模型、OLLAMA_CONTEXT_LENGTH 或基于 VRAM 的默认值。要在不重建 Modelfile 的情况下限制或强制 Ollama 的每请求运行时上下文，请设置 params.num_ctx；无效、零、负数和非有限值会被忽略。OpenAI 兼容的 Ollama 适配器仍会默认根据已配置的 params.num_ctx 或 contextWindow 注入 options.num_ctx；如果你的上游拒绝 options，请用 injectNumCtxForOpenAICompat: false 禁用它。

原生 Ollama 模型条目还接受 params 下的常见 Ollama 运行时选项，包括 temperature、top_p、top_k、min_p、num_predict、stop、repeat_penalty、num_batch、num_thread 和 use_mmap。OpenClaw 只转发 Ollama 请求键，因此不会把 OpenClaw 运行时参数（如 streaming）泄漏给 Ollama。使用 params.think 或 params.thinking 发送顶层 Ollama think；false 会为 Qwen 风格的思考模型禁用 API 级别思考。

{
  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 可以为特定已配置模型禁用或强制 Ollama API 思考。当活动运行只有隐式默认 off 时，OpenClaw 会保留这些显式模型参数；非 off 运行时命令（如 /think medium）仍会覆盖活动运行。

OpenClaw 默认会将名称中包含 deepseek-r1、reasoning 或 think 等内容的模型视为具备推理能力。

ollama pull deepseek-r1:32b

不需要额外配置。OpenClaw 会自动标记它们。

Ollama 免费并在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。

内置 Ollama 插件会为 memory search 注册一个记忆嵌入提供商。它使用已配置的 Ollama 基础 URL 和 API 密钥，调用 Ollama 当前的 /api/embed 端点，并在可能时将多个记忆块批处理到一个 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,
        },
      },
    },
  },
}

OpenClaw 的 Ollama 集成默认使用原生 Ollama API（/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"。

在带有 NVIDIA/CUDA 的 WSL2 上，官方 Ollama Linux 安装程序会创建一个带有 Restart=always 的 ollama.service systemd 单元。如果该服务自动启动，并在 WSL2 启动期间加载由 GPU 支持的模型，Ollama 可能会在模型加载时固定主机内存。Hyper-V 内存回收并不总是能回收这些固定页面，因此 Windows 可能会终止 WSL2 VM，systemd 又会再次启动 Ollama，循环随之重复。

常见证据：

• Windows 侧反复出现 WSL2 重启或终止
• WSL2 启动后不久，app.slice 或 ollama.service 中 CPU 占用较高
• 来自 systemd 的 SIGTERM，而不是 Linux OOM-killer 事件

当 OpenClaw 检测到 WSL2、启用了带有 Restart=always 的 ollama.service，并且可见 CUDA 标记时，会记录启动警告。

缓解措施：

sudo systemctl disable ollama

在 Windows 侧将以下内容添加到 %USERPROFILE%\.wslconfig，然后运行 wsl --shutdown：

[experimental]
autoMemoryReclaim=disabled

在 Ollama 服务环境中设置更短的 keep-alive，或者只在需要时手动启动 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

如果你的模型未列出，请在本地拉取该模型，或在 models.providers.ollama 中显式定义它。

ollama list  # 查看已安装内容
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # 或另一个模型

检查 Ollama 是否在正确端口上运行：

# 检查 Ollama 是否正在运行
ps aux | grep ollama

# 或重启 Ollama
ollama serve

从运行 Gateway 网关的同一台机器和运行时进行验证：

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

常见原因：

• baseUrl 指向 localhost，但 Gateway 网关在 Docker 中或另一台主机上运行。
• URL 使用 /v1，这会选择 OpenAI 兼容行为，而不是原生 Ollama。
• 远程主机需要在 Ollama 侧更改防火墙或 LAN 绑定。
• 模型存在于你的笔记本电脑守护进程上，但不在远程守护进程上。

这通常意味着提供商正在使用 OpenAI 兼容模式，或者模型无法处理工具架构。

优先使用原生 Ollama 模式：

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

如果小型本地模型在工具架构上仍然失败，请在该模型条目上设置 compat.supportsTools: false，然后重新测试。

Hosted Kimi/GLM 响应如果是很长的非语言符号串，会被视为失败的提供商输出，而不是成功的助手回答。这样正常的重试、回退或错误处理就能接管，而不会把损坏文本持久化到会话中。

如果反复发生，请捕获原始模型名称、当前会话文件，以及本次运行使用的是 Cloud + Local 还是 Cloud only，然后尝试一个新的会话和一个回退模型：

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

大型本地模型在流式传输开始前可能需要很长的首次加载时间。将超时范围限定到 Ollama 提供商，并且可以选择让 Ollama 在轮次之间保持模型已加载：

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

如果主机本身接受连接很慢，timeoutSeconds 也会延长此提供商受保护的 Undici 连接超时。

许多 Ollama 模型声明的上下文大于你的硬件可以舒适运行的范围。原生 Ollama 会使用 Ollama 自身的运行时上下文默认值，除非你设置 params.num_ctx。当你想要可预测的首个 token 延迟时，请同时限制 OpenClaw 的预算和 Ollama 的请求上下文：

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

如果 OpenClaw 发送了过多提示词，请先降低 contextWindow。如果 Ollama 正在加载对这台机器来说过大的运行时上下文，请降低 params.num_ctx。如果生成运行时间过长，请降低 maxTokens。