跳转到主要内容
OpenClaw 使用 Ollama 的原生 API（/api/chat），而不是兼容 OpenAI 的 /v1 端点。支持三种模式：
模式使用内容
云 + 本地可访问的 Ollama 主机，用于提供本地模型以及（如果已登录）:cloud 模型
仅云直接使用 https://ollama.com，不需要本地守护进程
仅本地可访问的 Ollama 主机，仅使用本地模型
如需使用专用 ollama-cloud 提供商 ID 进行仅云设置，请参见 Ollama Cloud。当你希望云路由与本地 ollama 提供商分开时，请使用 ollama-cloud/<model> 引用。
不要使用兼容 OpenAI 的 /v1 URL（http://host:11434/v1）。它会破坏工具调用，模型可能会把原始工具调用 JSON 作为纯文本输出。请使用原生 URL：baseUrl: "http://host:11434"（没有 /v1）。
规范配置键是 baseUrl。baseURL 也会被接受，以兼容 OpenAI SDK 风格示例，但新配置应使用 baseUrl。

​
凭证规则

Loopback、专用网络、.local 和裸主机名 Ollama URL 不需要真实 bearer token。OpenClaw 会为这些地址使用 ollama-local 标记。
公共远程主机和 https://ollama.com 需要真实凭证：OLLAMA_API_KEY、凭证配置文件或提供商的 apiKey。对于直接托管使用，优先使用 ollama-cloud 提供商。
带有 api: "ollama" 的自定义提供商遵循相同规则。例如，指向专用 LAN 主机的 ollama-remote 提供商可以使用 apiKey: "ollama-local"；子智能体会通过 Ollama 提供商钩子解析该标记，而不是把它当作缺失凭证处理。agents.defaults.memorySearch.provider 也可以指向自定义提供商 ID，让嵌入使用该 Ollama 端点。
auth-profiles.json 存储某个提供商 ID 的凭证；将端点设置（baseUrl、api、模型、headers、timeouts）放在 models.providers.<id> 中。较旧的扁平文件，例如 { "ollama-windows": { "apiKey": "ollama-local" } }，不是运行时格式；openclaw doctor --fix 会将它们重写为规范的 ollama-windows:default API key 配置文件并创建备份。该旧文件中的 baseUrl 值是噪声，应移到提供商配置中。
Ollama 记忆嵌入的 bearer 凭证仅限用于声明它的主机：
  • 提供商级密钥只会发送到该提供商的主机。
  • agents.*.memorySearch.remote.apiKey 只会发送到其远程嵌入主机。
  • 纯 OLLAMA_API_KEY 环境变量值会被视为 Ollama Cloud 约定，默认不会发送到本地/自托管主机。

​
入门指南

1

运行新手引导

openclaw onboard
选择 Ollama，然后选择一种模式：云 + 本地、仅云 或 仅本地。
2

选择模型

Cloud only 会提示输入 OLLAMA_API_KEY 并建议托管云默认值。Cloud + Local 和 Local only 会提示输入 Ollama 基础 URL，发现可用模型，并在缺少所选本地模型时自动拉取。已安装的 :latest 标签（例如 gemma4:latest）只显示一次，而不会重复显示 gemma4。Cloud + Local 还会检查该主机是否已登录以访问云模型。
3

验证

openclaw models list --provider ollama
非交互式：
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk
--custom-base-url 和 --custom-model-id 是可选的；省略它们会使用本地默认主机和建议的 gemma4 模型。

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

Cloud + Local 会通过一个可访问的 Ollama 主机路由本地模型和 :cloud 模型，这是 Ollama 的混合流程，也是你希望同时使用两者时应在设置期间选择的模式。 OpenClaw 会提示输入基础 URL，发现本地模型，并检查 ollama signin 状态。登录后，它会建议托管默认值（kimi-k2.5:cloud、minimax-m2.7: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/kimi-k2.5:cloud
openclaw onboard 期间显示的云模型列表会从 https://ollama.com/api/tags 实时填充，上限为 500 条，因此选择器会反映当前托管目录。如果 ollama.com 无法访问或在设置时未返回模型，OpenClaw 会回退到其硬编码建议列表，以便新手引导仍能完成。

​
模型发现（隐式提供商）

当已设置 OLLAMA_API_KEY（或凭证配置文件），且既未定义 models.providers.ollama，也未定义另一个带有 api: "ollama" 的自定义提供商时，OpenClaw 会从 http://127.0.0.1:11434 发现模型：
行为详细信息
目录查询/api/tags
能力检测尽力通过 /api/show 读取 contextWindow、num_ctx Modelfile 参数和能力（vision/tools/thinking）
视觉模型来自 /api/show 的 vision 能力会将模型标记为支持图像（input: ["text", "image"]）
推理检测可用时使用来自 /api/show 的 thinking 能力；当 Ollama 省略能力时，回退到名称启发式规则（r1、reason、reasoning、think）。无论报告的能力如何，glm-5.2:cloud 和 deepseek-v4-flash|pro:cloud 始终会被视为推理模型。
Token 限制maxTokens 默认使用 OpenClaw 的 Ollama 最大 token 上限
成本所有成本均为 0
ollama list
openclaw models list
使用显式 models 数组设置 models.providers.ollama，或使用带有 api: "ollama" 和非 loopback baseUrl 的自定义提供商，会禁用自动发现；随后必须手动定义模型（参见配置）。指向托管 https://ollama.com 的 models.providers.ollama 条目也会跳过发现，因为 Ollama Cloud 模型由提供商管理。像 http://127.0.0.2:11434 这样的 loopback 自定义提供商仍会计为本地，并保留自动发现。 你可以使用完整引用，例如 ollama/<pulled-model>:latest，而无需手写 models.json 条目；OpenClaw 会实时解析它。对于已登录主机，选择未列出的 ollama/<model>:cloud 引用会使用 /api/show 验证该精确模型，并且只有在 Ollama 确认元数据后才会将其添加到运行时目录；拼写错误仍会作为未知模型失败。

​
冒烟测试

对于跳过完整智能体工具表面的窄文本探测： 
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Reply with exactly: pong" \
    --json
为精简的视觉模型探测添加带图像的 --file（接受 PNG/JPEG/WebP；非图像文件会在调用 Ollama 前被拒绝，请使用 openclaw infer audio transcribe 处理音频）： 
OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Describe this image in one sentence." \
    --file ./photo.jpg \
    --json
这两条路径都不会加载聊天工具、记忆或会话上下文。如果它成功而普通智能体回复失败，问题很可能在于模型的工具/智能体能力，而不是端点。 使用 /model ollama/<model> 选择模型是精确的用户选择：如果配置的 baseUrl 无法访问，下一次回复会因提供商错误而失败，而不是静默回退到另一个已配置模型。 隔离的 cron 作业会在启动智能体轮次前添加一项本地安全检查：如果所选模型解析到本地/专用网络/.local Ollama 提供商，并且 /api/tags 无法访问，OpenClaw 会将该运行记录为 skipped，并在错误文本中包含该模型。此端点检查会按主机缓存 5 分钟，因此针对已停止守护进程的重复 cron 作业不会全部启动失败请求。 实时验证： 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts
对于 Ollama Cloud，将同一个实时测试指向托管端点（默认跳过 embeddings；如果需要强制启用，请使用 OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1，因为 cloud key 可能未授权 /api/embed）： 
export OLLAMA_API_KEY='<your-ollama-cloud-api-key>'
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 \
OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \
OPENCLAW_LIVE_OLLAMA_MODEL=glm-5.1:cloud \
OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=1 \
pnpm test:live -- extensions/ollama/ollama.live.test.ts
要添加模型，拉取它后就会被自动发现： 
ollama pull mistral

​
节点本地推理

智能体可以将一个短任务委托给已配对桌面或服务器节点上的 Ollama 模型。prompt 和响应会通过现有已认证的 Gateway 网关/节点连接传递；请求在节点自己的 loopback Ollama 端点（http://127.0.0.1:11434）上运行。
1

在节点上启动 Ollama

ollama pull qwen3:0.6b
ollama list
2

连接节点主机

openclaw node run \
  --host <gateway-host> \
  --port 18789 \
  --display-name "Local inference"
在 Gateway 网关主机上批准设备及其节点命令，然后验证：
openclaw devices list
openclaw devices approve <deviceRequestId>
openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes status --connected
首次连接，或添加 Ollama 命令的升级，可能会触发节点命令审批。如果节点连接时没有通告 ollama.models 和 ollama.chat，请再次检查 openclaw nodes pending。
3

从智能体使用它

内置 Ollama 插件会暴露 node_inference 工具。智能体先调用 action: "discover"，然后使用该结果中的节点和模型调用 action: "run"（当恰好连接了一个具备能力的节点时，run 可以省略节点）。例如：“发现我的节点上的 Ollama 模型，然后使用加载最快的模型来总结这段文本。”
Discovery 会读取 /api/tags，检查 /api/show 能力，并在可用时使用 /api/ps 优先排序已加载的模型。它只返回 Ollama 报告为支持聊天（completion 能力）的本地模型 — Ollama Cloud 行和仅 embedding 模型会被排除。每次运行都会禁用模型 thinking，并默认将输出设为 512 个 token（硬上限 8192），除非工具调用请求不同的 maxTokens；某些模型（例如 GPT-OSS）不支持禁用 thinking，可能仍会输出推理 token。 要让 Ollama 在节点上保持运行但不暴露给智能体： 
openclaw config set plugins.entries.ollama.config.nodeInference.enabled false
重启节点（openclaw node restart，或者对于前台会话，停止并重新运行 openclaw node run）。该节点会停止通告 ollama.models 和 ollama.chat；Ollama 本身以及 Gateway 网关的 Ollama provider 不受影响。将该值改回 true 并重启即可重新启用；变更后的命令面可能需要在重新连接后再次通过 openclaw nodes pending 审批。 不经过智能体轮次，直接验证节点命令： 
openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.models \
  --params '{}' \
  --invoke-timeout 90000 \
  --timeout 100000

openclaw nodes invoke \
  --node "Local inference" \
  --command ollama.chat \
  --params '{"model":"qwen3:0.6b","prompt":"Reply with exactly: pong","maxTokens":32,"timeoutMs":120000}' \
  --invoke-timeout 130000 \
  --timeout 140000
--invoke-timeout 限制节点运行命令的时长； --timeout 限制整体 Gateway 网关调用，并且应设置得更大。 节点本地推理始终使用节点自己的 loopback 端点 — 它不会复用已配置的远程/cloud models.providers.ollama.baseUrl。节点命令默认可用于 macOS、Linux 和 Windows 节点主机，并且仍受常规节点配对/命令策略约束。

​
视觉和图像描述

内置 Ollama 插件会将 Ollama 注册为支持图像的媒体理解提供商，因此 OpenClaw 可以通过本地或托管的 Ollama 视觉模型路由显式的图像描述请求和已配置的图像模型默认值。 
ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --json
--model 必须是完整的 <provider/model> ref；设置后，infer image describe 会先尝试该模型，而不是对已经支持原生视觉的模型跳过描述。如果调用失败，OpenClaw 可以继续通过 agents.defaults.imageModel.fallbacks；文件/URL 准备错误会在尝试 fallback 之前失败。将 infer image describe 用于 OpenClaw 的图像理解流程和已配置的 imageModel；将 infer model run --file 用于带自定义 prompt 的原始多模态探测。 要让 Ollama 成为入站媒体的默认图像理解提供商： 
{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}
优先使用完整的 ollama/<model> ref。裸 imageModel ref，例如 qwen2.5vl:7b，只有当该精确模型列在 models.providers.ollama.models 下且具有 input: ["text", "image"]，并且没有其他已配置的图像提供商暴露相同裸 id 时，才会规范化为 ollama/qwen2.5vl:7b；否则请显式使用提供商前缀。 较慢的本地视觉模型可能需要比 cloud 模型更长的图像理解超时，并且如果 Ollama 尝试分配模型完整通告的视觉上下文，可能会在受限硬件上崩溃。请设置能力超时并限制 num_ctx： 
{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "qwen2.5vl:7b",
            name: "qwen2.5vl:7b",
            input: ["text", "image"],
            params: { num_ctx: 2048, keep_alive: "1m" },
          },
        ],
      },
    },
  },
  tools: {
    media: {
      image: {
        timeoutSeconds: 180,
        models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }],
      },
    },
  },
}
该超时适用于入站图像理解以及显式的 image 工具。models.providers.ollama.timeoutSeconds 仍控制正常模型调用的底层 Ollama HTTP 请求保护。 实时验证： 
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
  pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts
如果你手动定义 models.providers.ollama.models，请显式标记视觉模型： 
{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}
OpenClaw 会拒绝对未标记为支持图像的模型发起图像描述请求。使用隐式发现时，这来自 /api/show 的视觉能力。

​
配置

export OLLAMA_API_KEY="ollama-local"
如果设置了 OLLAMA_API_KEY，你可以在 provider 条目中省略 apiKey；OpenClaw 会为可用性检查填充它。

​
常见配方

将模型 ID 替换为 ollama list 或 openclaw models list --provider ollama 中的精确名称。
与 Gateway 网关位于同一台机器上的 Ollama，会自动发现：
ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4
除非你需要手动模型，否则不要添加 models.providers.ollama 块。
{
  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。当硬件无法运行模型完整通告的上下文时，请保持二者一致。
无本地守护进程，直接使用托管模型：
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" },
    },
  },
}
要使用专用的 ollama-cloud provider id 而不是这种形态，请参阅 Ollama 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 前移除当前提供商前缀（并回退到裸 ollama/ 前缀），因此 ollama-large/qwen3.5:27b 会以 qwen3.5:27b 到达 Ollama。
一些本地模型可以处理简单提示词，但难以承载完整的智能体工具表面。请先限制工具和上下文，再触碰全局运行时设置：
{
  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 },
          },
        ],
      },
    },
  },
}
仅当模型或服务器在工具 schema 上会可靠失败时，才使用 compat.supportsTools: false，它会用智能体能力换取稳定性。除非明确需要，localModelLean 会从直接智能体表面移除重量级浏览器、cron、消息、媒体生成、语音和 PDF 工具，并把更大的目录放到工具搜索后面。它不会更改 Ollama 的运行时上下文或思考模式。对于会循环或把预算花在隐藏推理上的小型 Qwen 风格思考模型，请搭配 params.num_ctx 和 params.thinking: false 使用。

​
模型选择

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}
自定义提供商 ID 的工作方式相同：对于使用当前提供商前缀的引用，例如 ollama-spark/qwen3:32b，OpenClaw 会在调用 Ollama 前移除该前缀，并发送 qwen3:32b。 对于较慢的本地模型，优先使用提供商作用域的调优，而不是提高整个智能体运行时超时： 
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
timeoutSeconds 覆盖模型 HTTP 请求：连接建立、标头、正文流式传输，以及受保护 fetch 的总中止时间。params.keep_alive 会在原生 /api/chat 请求中作为顶层 keep_alive 转发；当首轮加载时间是瓶颈时，请按模型设置它。

​
快速验证

# Ollama daemon visible to this machine
curl http://127.0.0.1:11434/api/tags

# OpenClaw catalog and selected model
openclaw models list --provider ollama
openclaw models status

# Direct model smoke
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"
对于远程主机，请将 127.0.0.1 替换为 baseUrl 主机。如果 curl 可用但 OpenClaw 不可用，请检查 Gateway 网关是否运行在不同的机器、容器或服务账号下。

​
Ollama Web 搜索

OpenClaw 将 Ollama Web 搜索 内置为 web_search 提供商。
属性详情
主机设置时使用 models.providers.ollama.baseUrl，否则使用 http://127.0.0.1:11434；https://ollama.com 直接使用托管 API
认证对已登录的本地主机无需密钥；对于直接 https://ollama.com 搜索或受认证保护的主机，使用 OLLAMA_API_KEY 或已配置的提供商认证
要求本地/自托管主机必须正在运行并已通过 ollama signin 登录；直接托管搜索需要 baseUrl: "https://ollama.com" 加真实 API 密钥
在 openclaw onboard 或 openclaw configure --section web 期间选择它，或设置： 
{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}
对于通过 Ollama Cloud 进行的直接托管搜索： 
{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }],
      },
    },
  },
  tools: {
    web: {
      search: { provider: "ollama" },
    },
  },
}
对于自托管主机，OpenClaw 会先尝试本地 /api/experimental/web_search 代理，然后回退到同一主机上的托管 /api/web_search 路径；已登录的本地守护进程通常会通过本地代理响应。直接 https://ollama.com 调用始终使用托管的 /api/web_search 端点。
完整设置和行为请参阅 Ollama Web 搜索。

​
高级配置

此模式下工具调用并不可靠。 仅当代理需要 OpenAI 格式且你不依赖原生工具调用时才使用它。
对 /v1/chat/completions 后面的代理显式设置 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 }。OpenClaw 在此模式下默认注入 options.num_ctx，这样 Ollama 不会静默回退到 4096 token 上下文。如果你的代理拒绝未知的 options 字段，请禁用它：
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: false,
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}
对于自动发现的模型，OpenClaw 会使用 /api/show 报告的上下文窗口，包括来自自定义 Modelfile 的更大 PARAMETER num_ctx 值；否则会回退到 OpenClaw 的默认 Ollama 上下文窗口。提供商级别的 contextWindow、contextTokens 和 maxTokens 会为该提供商下的每个模型设置默认值，并且可以按模型覆盖。contextWindow 是 OpenClaw 自己的提示词/压缩预算。原生 /api/chat 请求会保持 options.num_ctx 未设置，除非你显式设置 params.num_ctx，因此 Ollama 会应用自己的模型、OLLAMA_CONTEXT_LENGTH 或基于 VRAM 的默认值；无效、零、负数或非有限的 params.num_ctx 值会被忽略。如果旧配置只使用 contextWindow/maxTokens 来强制原生请求上下文，请运行 openclaw doctor --fix 将它们复制到 params.num_ctx。OpenAI 兼容适配器仍会默认从已配置的 params.num_ctx 或 contextWindow 注入 options.num_ctx；如果上游拒绝 options，请使用 injectNumCtxForOpenAICompat: false 禁用。原生模型条目还接受 params 下的常见 Ollama 运行时选项，并作为原生 /api/chat options 转发：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 和 num_thread。少数键（format、keep_alive、truncate、shift）会作为顶层请求字段转发，而不是嵌套在 options 中。OpenClaw 只会转发这些 Ollama 请求键，因此仅运行时参数（如 streaming）永远不会发送给 Ollama。使用 params.think（或 params.thinking）设置顶层 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 也可用；如果两者都设置，显式的提供商模型条目优先。
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 可以为特定模型禁用或强制启用 API thinking。当活动运行只有隐式的 off 默认值时，OpenClaw 会保留该显式配置； 非 off 的运行时命令（例如 /think medium）仍会覆盖它。truthy thinking 请求绝不会发送到显式标记为 reasoning: false 的模型；think: false 请求则始终会发送。
名为 deepseek-r1、reasoning、reason 或 think 的模型默认会被视为 具备推理能力，无需额外配置：
ollama pull deepseek-r1:32b
Ollama 在本地运行且免费，因此自动发现和手动定义的所有模型成本都是 0。
内置 Ollama 插件会为记忆搜索注册一个记忆嵌入提供商。 它使用已配置的 Ollama 基础 URL 和 API key，调用 /api/embed，并在可能时将多个记忆分块批处理为一个 input 请求。当 proxy.enabled=true 时，发送到从已配置 baseUrl 推导出的精确主机本地 local loopback 源的嵌入请求，会使用 OpenClaw 的受保护直连路径，而不是托管转发代理。 已配置的主机名本身必须是 localhost 或 loopback IP 字面量；仅解析到 loopback 的 DNS 名称仍会使用托管代理路径。 LAN、tailnet、私有网络和公共 Ollama 主机始终保留在托管代理路径上，重定向到其他主机/端口也不会继承信任。 proxy.loopbackMode: "proxy" 仍会通过代理路由 loopback 流量；proxy.loopbackMode: "block" 会在连接前拒绝它。请参阅托管代理。
属性值
默认模型nomic-embed-text
自动拉取是，如果本地不存在
默认内联并发1（其他提供商默认更高；如果主机可以承受，可用 nonBatchConcurrency 提高）
查询时嵌入会为要求或推荐检索前缀的模型使用检索前缀：nomic-embed-text、qwen3-embedding 和 mxbai-embed-large。文档批次保持原始格式，因此现有索引无需格式迁移。
{
  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,
        },
      },
    },
  },
}
Ollama 默认使用原生 API（/api/chat），它同时支持流式传输和工具调用，无需特殊配置。对于原生请求，thinking 控制会直接转发：/think off 和 openclaw agent --thinking off 会发送顶层 think: false，除非显式配置了 params.think/params.thinking；/think low|medium|high 会发送匹配的 effort 字符串；/think max 会映射到 Ollama 的最高 effort， 即 think: "high"。
如需改用 OpenAI 兼容端点，请参阅上方的“旧版 OpenAI 兼容模式”；在那里，流式传输和工具调用可能无法同时工作。

​
故障排查

在配备 NVIDIA/CUDA 的 WSL2 上，官方 Ollama Linux 安装程序会创建一个带有 Restart=always 的 ollama.service systemd 单元。如果该服务自动启动，并在 WSL2 启动期间加载 GPU 支持的模型， Ollama 可能会在加载时占住主机内存；Hyper-V 内存回收并不总能回收这些页面，因此 Windows 可能会终止 WSL2 VM， systemd 随后重启 Ollama，循环就会重复。证据：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
或缩短 keep-alive / 仅在需要时手动启动 Ollama：
export OLLAMA_KEEP_ALIVE=5m
ollama serve
请参阅 ollama/ollama#11317。
确认 Ollama 正在运行，已设置 OLLAMA_API_KEY（或身份验证配置档），并且未显式定义 models.providers.ollama：
ollama serve
curl http://localhost:11434/api/tags
在本地拉取模型，或在 models.providers.ollama 中显式定义它：
ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve
从运行 Gateway 网关的同一台机器和运行时验证：
openclaw gateway status --deep
curl http://ollama-host:11434/api/tags
常见原因：
  • baseUrl 指向 localhost，但 Gateway 网关在 Docker 中或另一台主机上运行。
  • URL 使用 /v1，选择了 OpenAI 兼容行为，而不是原生 Ollama。
  • 远程主机需要更改防火墙或 LAN 绑定。
  • 模型位于你的笔记本电脑守护进程中，但不在远程守护进程中。
通常是提供商处于 OpenAI 兼容模式，或模型无法处理工具架构。优先使用原生模式：
{
  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 提供商，并可选择在轮次之间保持模型已加载：
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
如果主机本身接受连接较慢，timeoutSeconds 也会延长该提供商的受保护连接超时。
许多模型声明的上下文大于你的硬件可以舒适运行的范围。原生 Ollama 会使用自己的运行时默认值，除非设置了 params.num_ctx。同时限制 OpenClaw 的预算和 Ollama 的请求上下文，以获得可预测的首个 token 延迟：
{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}
如果 OpenClaw 发送的 prompt 过多，请降低 contextWindow。如果 Ollama 的运行时上下文对该机器过大， 请降低 params.num_ctx。如果生成运行时间过长，请降低 maxTokens。
更多帮助：故障排查和常见问题。

​
相关内容

Ollama Cloud

使用专用 ollama-cloud 提供商进行仅云端设置。

模型提供商

所有提供商、模型引用和故障转移行为的概览。

模型选择

如何选择和配置模型。

Ollama Web 搜索

Ollama 驱动的 Web 搜索的完整设置和行为详情。

配置

完整配置参考。