配方

常见配方¶

将模型 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: [] 配置自托管端点，以保持自动发现可用。

局域网 Ollama 主机与手动模型

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            reasoning: true,
            input: ["text"],
            contextTokens: 32768,
            params: {
              num_ctx: 32768,
              thinking: false,
              keep_alive: "15m",
            },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/qwen3.5:9b" },
    },
  },
}

contextTokens 限制 OpenClaw 的活跃输入预算；params.num_ctx 设置 Ollama 的请求上下文。当硬件无法运行模型完整标称上下文时，请保持两者一致。

仅 Ollama Cloud

无本地守护进程，直接使用托管模型：

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 主机

运行多个 Ollama 服务器时使用自定义 provider ID；每个服务器拥有自己的主机、模型、身份验证和超时。

{
  models: {
    providers: {
      "ollama-fast": {
        baseUrl: "http://mini.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"], contextTokens: 32768 },
        ],
      },
      "ollama-large": {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 420,
        maxTokens: 16384,
        models: [
          { id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"], contextTokens: 131072 },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama-fast/gemma4",
        fallbacks: ["ollama-large/qwen3.5:27b"],
      },
    },
  },
}

OpenClaw 在调用 Ollama 之前会移除当前 provider 前缀（回退到裸 ollama/ 前缀），因此 ollama-large/qwen3.5:27b 会以 qwen3.5:27b 的形式到达 Ollama。

小型本地模型配置

本地 Ollama 模型在 tools.toolSearch 未设置时会自动使用结构化工具搜索。这会在需要时才加载其 schema，同时保持可选能力可用。设置过程不会启用精简模式。 App、交互式 CLI 和非交互式设置使用 32,768 个 token 的运行时上下文；如果更小，则使用模型的原生窗口。标称的原生窗口会单独保留；已知的云端路由保留其托管上下文。大文件读取使用 OpenClaw 的基于上下文的分页。原生适配器会保留这些文本页面及其继续指令；结构化回退数据会单独限制。将任何显式上下文覆盖限制在主机可支持的范围内：

{
  agents: {
    entries: {
      local: {
        default: true,
        model: { primary: "ollama/gemma4" },
      },
    },
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          {
            id: "gemma4",
            name: "gemma4",
            input: ["text"],
            contextTokens: 32768,
            params: { num_ctx: 32768 },
          },
        ],
      },
    },
  },
}

显式的 tools.toolSearch 设置优先，包括 false。工具搜索不会更改 Ollama 的上下文或思考模式。Ollama 思考默认关闭；显式的思考设置可以独立更改它。如果你之前启用了 localModelLean，请将其设置为 false，以恢复可选工具，同时保留自动工具搜索。

仅当模型或服务器在工具 schema 上持续失败时，才使用 compat.supportsTools: false；它会完全禁用工具使用。对于有意范围更窄的 agent，请优先使用 tools.profile 或按 agent 的工具策略。

模型选择¶

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

自定义提供商 ID 的工作方式相同：对于使用当前提供商前缀的 ref，例如 ollama-spark/qwen3:32b，OpenClaw 会在调用 Ollama 之前剥离该前缀，并发送 qwen3:32b。

对于较慢的本地模型，在提高整个 agent 运行时超时之前，请优先进行提供商范围的调优：

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

timeoutSeconds 覆盖模型 HTTP 请求：连接建立、请求头、正文流式传输，以及整体 guarded-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 是否运行在不同的机器、容器或服务账户上。

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