模型与 Provider

这一课你将能做到

1. 用 openclaw models 查看、切换、设置默认模型
2. 在配置里接入 Anthropic / OpenAI / Ollama 三种 provider
3. 设计「简单任务用轻量模型，复杂任务用主力模型」的分层策略

为什么要学

团队 bot 怕两种烧钱：一是「问个早安也调了最贵的大模型」，二是「复杂任务塞给轻量模型，结果出错还得人修」。OpenClaw 支持多 provider 并存的模型路由，选对了模型组合，既省钱又保质量。

人话：这一课教你怎么给 bot 配一个「性价比合理的大脑」。

先建立图像

OpenClaw 的模型体系三层结构：

Provider（模型厂商）
  ├── Anthropic  → Claude 系列（Sonnet / Opus / Haiku）
  ├── OpenAI     → GPT 系列（4o / o1 / o3-mini）
  ├── Ollama     → 本地模型（Llama / Qwen / DeepSeek-Coder）
  └── …（Gemini、Groq、DeepSeek API 等）

模型层
  ├── 主力模型（systemAgent）：日常对话、复杂任务
  ├── 推理模型（reasoningAgent）：数学、代码、深度分析
  └── 图像/嵌入模型（可选）

配置层：~/.openclaw/openclaw.json
  agents.defaults.systemAgent.model → 默认主力
  agents.defaults.systemAgent.reasoningAgent.model → 推理任务

跟着做

步骤 1：查看当前模型

openclaw models status
openclaw models list --json

步骤 2：设置默认模型

openclaw models set claude-sonnet-4-20250514

步骤 3：配置多 Provider

编辑 ~/.openclaw/openclaw.json：

{
  "agents": {
    "defaults": {
      "systemAgent": {
        "model": "claude-sonnet-4-20250514",
        "provider": "anthropic"
      },
      "reasoningAgent": {
        "model": "claude-3-opus",
        "provider": "anthropic"
      }
    }
  },
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}"
      },
      "openai": {
        "apiKey": "${OPENAI_API_KEY}"
      }
    }
  }
}

步骤 4：接入 Ollama（零 API 费用方案）

# 安装 Ollama 并拉模型
ollama pull qwen2.5:14b

# 配置 OpenClaw 使用 Ollama（默认本地 http://localhost:11434）
openclaw models set qwen2.5:14b --provider ollama

步骤 5：验证切换

openclaw infer "你好，你是谁？" --model claude-sonnet-4-20250514
openclaw infer "你好，你是谁？" --model qwen2.5:14b

两条命令分别走不同 provider 和模型，对比输出质量。

讲清楚要点

1. 设置模型用 models set，不是改 agents 配置：openclaw models set 同时更新默认 provider 和模型，并做有效性校验；直接改 agents 配置若 model 写错会导致启动报错。
2. 环境变量引用 ${ANTHROPIC_API_KEY} 是推荐方式：避免把密钥写死在 JSON 里，也便于 CI/容器注入。
3. Ollama 适合局域网/无公网场景：模型跑在本地或内网服务器，调用不经过互联网，安全但速度受限于本地硬件。
4. 模型列表是动态的：openclaw models refresh 刷新 provider 的可用模型列表，厂商发新模型后不必等更新就能看到。
5. 扫描命令探测兼容模型：openclaw models scan 探测当前 provider 下可用且被 catalog 收录的模型，避免写错模型名。

你可能会懵的地方

• reasoningAgent 和 systemAgent 什么关系？ systemAgent 是默认主力；reasoningAgent 是接到需要深度思考的任务时调用的另一套配置。可以配同一个模型，也可以分层——简单任务用轻量模型，推理任务用重模型。

• 多个 agent 能否各用各的模型？ 能。每个 agents.entries.<id> 可独立指定 model 和 provider。评审 bot 用便宜模型跑，值班 bot 用主力模型顶。

• provider 的 key 没生效？ 确认环境变量名完全匹配 JSON 里的占位符；Gateway 重启后生效；先用 openclaw infer 做本地推理测试，排除渠道层问题。

• Ollama 配完没反应？ 确认 Ollama 服务在跑（ollama list）；确认 localhost:11434 可达；OpenClaw 默认不指定 Ollama 的 baseURL 时走 http://localhost:11434/v1。

• 模型名更新了怎么同步？ openclaw models refresh 刷新 catalog；如果厂商刚发布的新模型还没被收录，models set 会存下你的选择并出警告，不影响使用。

错法对照

错法	问题	正解
把 API key 直接写进 JSON	密钥进日志、进 git、进备份	用 ${ENV_NAME} 引用环境变量
全场景都用最贵的模型	费用飙升，简单问答无意义	简单任务轻量模型，复杂任务主力模型
Ollama 没装服务就配	Gateway 推理调用报连接失败	先 ollama serve 确认本地服务可达
模型名写错（少一个版本号）	启动报错或推理失败	models list 查确认名，或 models scan 探测
只配 provider 没配 model	systemAgent 没有大脑	openclaw models set 明确指定默认模型

卡点急救

1. models status 报认证失败：先检查环境变量在 Gateway 进程的上下文中是否可见；systemd 服务要用 Environment= 或 wrapper 注入 key。
2. 模型列表为空：先 openclaw models refresh；再确认 provider 配置里 key 有效；最后看 provider 官网是否改了 API 端点。
3. Ollama 推理极慢：大模型跑在 CPU 上 vs GPU 差异巨大；ollama ps 看加载状态；确认模型量化级别（q4_k_m 通常够用）。

面试常问

• 如何在成本与质量间做模型分层？ 日常问答和轻量任务用轻量模型（Claude Haiku / GPT-4o-mini / 本地 Qwen），复杂分析、代码、安全任务用主力模型（Claude Sonnet / GPT-4o），数学或深度推理可选 reasoning 模型。OpenClaw 的 systemAgent 和 reasoningAgent 天然支持这种分层，按任务类型路由到不同配置。

• 团队无公网怎么跑 OpenClaw？ Ollama 本地部署 + OpenClaw 配置 Ollama provider，模型完全在内网运行；渠道侧走 Telegram 等出站连接即可收发消息，无需公网入站。本地硬件受限时可考虑在局域网内服务器部署 Ollama 并共享给多台 OpenClaw 实例。

• API key 泄露了怎么最小化止损？ 在 provider 控制台（Anthropic / OpenAI）直接删除并重置 key；更新环境变量；重启 Gateway（服务管理会自动重载）；用 openclaw doctor 确认无残留明文密钥。如果用了 SecretRef 方案，只在外部密钥管理器侧轮换即可。

自测三问

1. openclaw models set 与直接改 openclaw.json 的优缺点对比？
2. 为什么推荐用 ${ENV_NAME} 引用密钥而不是写死？
3. Ollama 方案在团队部署中的优势与局限各是什么？

小结一句话

给 bot 选大脑不是越贵越好：主力模型管质量、轻量模型管成本、Ollama 管安全离线，三层搭配才是生产级方案。

延伸

• Provider 与模型列表
• 模型配置参考
• 下一课：Channels 集成——把 bot 接入 Slack / Telegram / Discord，让它真正「住进」团队。