模型配置

支持的模型 Provider

OpenClaw 支持 60+ 种模型 Provider，涵盖云端 API、本地推理和代理网关。

类别	Provider 示例
国际主流	OpenAI、Anthropic Claude、Google Gemini、xAI Grok
国产模型	DeepSeek、千问 (Qwen)、月之暗面 (Kimi/Moonshot)、MiniMax、智谱 (GLM/Z.AI)、字节豆包 (Volcengine/Doubao)
本地推理	Ollama、LM Studio、vLLM、SGLang、inferrs、ds4
统一网关	OpenRouter、LiteLLM、Cloudflare AI Gateway、Vercel AI Gateway
云平台	Amazon Bedrock、NVIDIA、Groq、Together AI、Cerebras
其他	GitHub Copilot、Perplexity、Hugging Face Inference

openclaw.json 中的模型配置段

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      model: {
        primary: "deepseek/deepseek-v4-pro",       // 主模型
        fallbacks: ["openai/gpt-5.4", "anthropic/claude-sonnet-4-6"],  // 备选链
      },
    },
  },
}

模型引用格式：<provider>/<model-name>

# 查看已配置的模型
openclaw models list

# 查看特定 Provider 的可用模型
openclaw models list --provider deepseek

# 测试模型连通性
openclaw models status

环境变量管理

.env 文件方式

# ~/.openclaw/.env
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

或在 openclaw.json 中声明：

{
  env: {
    DEEPSEEK_API_KEY: "sk-...",
    ANTHROPIC_API_KEY: "sk-ant-...",
  },
}

不要硬编码密钥

绝对不要把 API Key 直接写在代码文件、Git 提交或公开分享的配置中。使用 .env 文件或环境变量。

各 Provider 认证方式

Provider	环境变量	Base URL
DeepSeek	DEEPSEEK_API_KEY	https://api.deepseek.com
OpenAI	OPENAI_API_KEY	https://api.openai.com/v1
Anthropic	ANTHROPIC_API_KEY	https://api.anthropic.com
Google Gemini	GEMINI_API_KEY	-
Qwen	DASHSCOPE_API_KEY	https://dashscope.aliyuncs.com/compatible-mode/v1
Ollama	（无需认证）	http://127.0.0.1:11434/v1
Moonshot	MOONSHOT_API_KEY	https://api.moonshot.cn/v1
Z.AI (GLM)	ZAI_API_KEY	https://open.bigmodel.cn/api/paas/v4

Fallback 链

Fallback 链是 OpenClaw 的核心韧性设计：主模型挂了，自动切备选模型。

{
  agents: {
    defaults: {
      model: {
        primary: "deepseek/deepseek-v4-pro",
        fallbacks: [
          "openai/gpt-5.4",              // 备选 1
          "anthropic/claude-sonnet-4-6",  // 备选 2
          "ollama/qwen3:14b",             // 本地兜底
        ],
      },
    },
  },
}

graph LR
    A[用户消息] --> B{主模型 DeepSeek V4 Pro}
    B -->|成功| G[返回结果]
    B -->|超时/报错| C{Fallback 1: GPT-5.4}
    C -->|成功| G
    C -->|超时/报错| D{Fallback 2: Claude}
    D -->|成功| G
    D -->|超时/报错| E{最后兜底: Ollama 本地}
    E --> G

Model Alias（模型别名）

{
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v4-pro" },
      models: {
        "deepseek/deepseek-v4-pro": { alias: "DeepSeek" },
        "openai/gpt-5.4": { alias: "GPT" },
      },
    },
  },
}

模型参数调优

{
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v4-pro" },
      models: {
        "deepseek/deepseek-v4-pro": {
          params: {
            temperature: 0.7,    // 0=严谨准确, 1=创意发散（默认 0.7）
            maxTokens: 8192,     // 单次回复最大 token 数
            topP: 0.9,           // nucleus sampling 阈值
          },
        },
      },
    },
  },
}

参数	默认值	说明
temperature	0.7	控制随机性：0 = 确定性的，1 = 高创造性
maxTokens	8192	单次最大输出 token，较长的回答需要更大的值
topP	1.0	核采样：只考虑累积概率达到 topP 的 token

经验：DeepSeek API 接入实战

安装 DeepSeek 插件

openclaw plugins install @openclaw/deepseek-provider
openclaw gateway restart

非交互式配置

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice deepseek-api-key \
  --deepseek-api-key "$DEEPSEEK_API_KEY" \
  --skip-health \
  --accept-risk

完整配置示例

{
  env: { DEEPSEEK_API_KEY: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
  agents: {
    defaults: {
      model: { primary: "deepseek/deepseek-v4-flash" },
      models: {
        "deepseek/deepseek-v4-flash": {
          alias: "DeepSeek V4 Flash",

          params: { temperature: 0.7, maxTokens: 16384 },
        },
        "deepseek/deepseek-v4-pro": {
          alias: "DeepSeek V4 Pro",

          params: { temperature: 0.7, maxTokens: 16384 },
        },
      },
    },
  },
}

DeepSeek V4 Thinking 模式

V4 模型支持 thinking 控制。对 Agent 发送 /think xhigh 或 /think max 启用深度思考模式，Agent 会在回答前深度推理。

经验：Ollama 本地模型接入

# 1. 安装并启动 Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama serve

# 2. 拉取模型
ollama pull qwen3:14b
ollama pull mistral:7b

# 3. 验证
curl http://127.0.0.1:11434/v1/models

// openclaw.json 配置
{
  agents: {
    defaults: {
      model: {
        primary: "ollama/qwen3:14b",
        fallbacks: ["deepseek/deepseek-v4-flash"],
      },
    },
  },
}

Ollama 本地模型的优势

• 完全离线：数据不离开本机
• 零 API 费用：电费 + 硬件折旧就是全部成本
• 低延迟：局域网内毫秒级响应
• 可控：可精调、用量不限

缺点：需要 GPU（14B 以上模型建议至少 16GB 显存），推理能力弱于顶级云端模型。

模型选择建议

场景	推荐方案
日常开发助手	deepseek/deepseek-v4-flash + ollama/qwen3:14b fallback
高难度推理	deepseek/deepseek-v4-pro（启用 thinking）或 anthropic/claude-opus-4-6
省钱离线	ollama/qwen3:14b 作为主模型
多模型兜底	主模型 → 备选模型 → 本地模型 三级 fallback
企业安全	敏感数据走 Ollama 本地，非敏感走云端 API

下一步

掌握了模型配置后，继续学习 故障排查 →

加载练习题中...

---

🎯 本章要点

• fallback 链在主模型失败时按顺序尝试备选模型
• Ollama、vLLM、LM Studio 支持本地推理，数据不出机器