OpenClaw 2026.3.8 + DeepSeek 配置实战：从“Unknown Model”到完美运行的避坑指南

摘要：本文记录了在 Windows WSL2 (Ubuntu) 环境下部署 OpenClaw 2026.3.8 并接入 DeepSeek 模型的全过程。重点复盘了配置校验严格、模型名强制重写（Anthropic Fallback）以及 Provider 匹配陷阱两大核心问题，并给出了基于"OpenAI 兼容模式"的最终解决方案。

📑 目录

背景与环境
[快速安装流程 (WSL2)](#快速安装流程 (WSL2) "#heading-3")
[遇到的"拦路虎" (踩坑复盘)](#遇到的“拦路虎” (踩坑复盘) "#heading-7")
[最终解决方案：OpenAI "伪装"法](#最终解决方案：OpenAI “伪装”法 "#heading-10")
验证与启动
常用命令备忘
给开发者的建议

📅 背景与环境

随着本地大模型应用的兴起，OpenClaw 作为一个新兴的开源 Agent 框架受到了关注。然而，在尝试将其与国产大模型 DeepSeek 对接时，由于版本迭代和内部逻辑的复杂性，遇到了不少"拦路虎"。

实验环境：

OS: Windows 11 + WSL2 (Ubuntu)
OpenClaw Version: 2026.3.8
Target Model : DeepSeek Chat (deepseek-chat)
API Compatibility: OpenAI Compatible

🤔 模型选择：为什么最后选了 DeepSeek？

本来打算选 Google Gemini，但由于国内网络连不上，综合费用考虑，最后选了 DeepSeek。

deepseek API Key 申请地址 ：platform.deepseek.com

关键点 ：OpenClaw 安装向导中 Model/auth provider没有提供 DeepSeek 这一选项选项，但因为 DeepSeek API 兼容 OpenAI 接口格式 ，所以可以通过 OpenAI 选项来接入！

🛠️ 快速安装流程 (WSL2)

如果你还没安装 OpenClaw，可以参考以下标准步骤：

1. 安装 WSL2 与 Ubuntu

在 Windows PowerShell (管理员) 中执行：

powershell 复制代码

wsl --install

重启电脑后，在开始菜单打开 Ubuntu，按提示设置用户名和密码。

2. 一键安装 OpenClaw

进入 Ubuntu 终端，执行官方安装脚本：

bash 复制代码

# 切换到用户主目录
cd ~

# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash

3. 初始化配置

运行 openclaw 启动向导。

关键策略 ：在选择模型提供商时，无法直接选择 DeepSeek，建议选择 OpenAI 作为占位，后续通过修改配置文件实现"曲线救国"。

⚠️ 遇到的"拦路虎" (踩坑复盘)

在配置过程中，我遇到了三个非常棘手的问题，如果不了解其内部逻辑，极易卡住。

❌ 困难一：JSON Schema 校验过于严格

现象：

试图在 openclaw.json 的 models 定义中添加 "description" 字段做备注时，Gateway 直接报错，提示"Unrecognized key: "description" "

原因分析 ：

OpenClaw 的配置文件校验极其严格，遵循严格的 JSON Schema，不支持任何非标准定义的额外字段。
💡 教训：配置文件必须"极简"，只保留官方文档明确列出的字段。

❌ 困难二：强制的"模型名重写"逻辑 (最顽固的 Bug)

现象：

即使将 provider 设为 deepseek，系统也会强制将模型 ID 转换为 anthropic/deepseek-chat。

即使将 provider 改为 openai 并指向 DeepSeek 地址，只要模型名中包含 deepseek 且未显式指定 Provider 前缀，系统依然会触发 fallback 逻辑，强行加上 anthropic/ 前缀。

结果导致路由表找不到 anthropic/deepseek-chat 的实现，报 Unknown model。

关键日志证据：

text 复制代码

[model-selection] Model "deepseek-chat" specified without provider. 
Falling back to "anthropic/deepseek-chat". 
Please use "anthropic/deepseek-chat" in your config.

原因分析 ：

从日志行为推断，OpenClaw 内置了一套模型名称自动推断机制 。当检测到模型名包含 "deepseek" 但未显式指定 Provider 时，系统会强制将其路由至 Anthropic 提供商。这极可能是为了兼容旧版本配置的遗留逻辑，但在当前版本中，由于 DeepSeek 并未配置在 Anthropic 路径下，导致了路由死循环。

💡 教训 ：不能依赖系统的自动推断，必须通过显式全限定名 （如 openai/deepseek-chat）来打破推断链。

✅ 最终解决方案：OpenAI "伪装"法

经过多次调试，我们采用了 "OpenAI Provider 欺骗法" + "显式全限定名" 的组合拳，成功跑通。

核心配置步骤

请编辑 ~/.openclaw/openclaw.json 文件，参考以下配置：

1. 认证配置 (Auth)

将默认 provider 设为 openai。

json 复制代码

"auth": {
  "profiles": {
    "default": {
      "provider": "openai",
      "mode": "api_key"
    }
  }
}

2. 模型配置 (Models) - 关键！

这里利用 openai provider，但将 baseUrl 指向 DeepSeek 的 API 地址。
注意：id 保持为 deepseek-chat，不要加前缀。

json 复制代码

"models": {
  "mode": "merge",
  "providers": {
    "openai": {
      "baseUrl": "https://api.deepseek.com/v1",
      "apiKey": "YOUR_MODEL_API_KEY", 
      "api": "openai-completions",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "deepseek-chat",
          "contextWindow": 128000
        }
      ]
    }
  }
}

3. Agent 默认模型 (Agents) - 最关键的一步！

在 agents.defaults.model.primary 中，必须使用 openai/deepseek-chat。
原理：显式带上 openai/ 前缀，告诉系统"这是 openai provider 下的 deepseek-chat 模型"，从而阻止系统触发"自动添加 anthropic/ 前缀"的 fallback 逻辑。

json 复制代码

"agents": {
  "defaults": {
    "model": {
      "primary": "openai/deepseek-chat"
    },
    "workspace": "/home/你的用户名/.openclaw/workspace",
    "compaction": {
      "mode": "safeguard"
    }
  }
}

4. 完整配置文件示例 (`openclaw.json`)

你可以直接参考以下完整结构（记得替换 Key 和用户名）：

json 复制代码

{

  "auth": {

    "profiles": {

      "default": {

        "provider": "openai",

        "mode": "api_key"

      }

    }

  },

  "models": {

    "mode": "merge",

    "providers": {

      "openai": {

        "baseUrl": "https://api.deepseek.com/v1",

        "apiKey": "YOU_MODEL_API_KEY",

        "api": "openai-completions",

        "models": [

          {

            "id": "deepseek-chat",

            "name": "deepseek-chat",

            "contextWindow": 128000

          }

        ]

      }

    }

  },

   "agents": {

    "defaults": {

      "model": {

        "primary": "openai/deepseek-chat"

      },

      "workspace": "/home/你的用户名/.openclaw/workspace",

      "compaction": {

        "mode": "safeguard"

      }

    }

  },

  "commands": {

    "native": "auto",

    "nativeSkills": "auto",

    "restart": true,

    "ownerDisplay": "raw"

  },

  "gateway": {

    "mode": "local",

    "auth": {

      "mode": "token",

      "token": "You_Token"

    }

  },

  "meta": {

    "lastTouchedVersion": "2026.3.8",

    "lastTouchedAt": "2026-03-10T18:20:00.000Z"

  }

}

🚀 验证与启动

配置完成后，通过两个终端窗口验证是否成功：

终端 A (启动 Gateway):

bash 复制代码

npx openclaw gateway --token "YOUR_GATEWAY_TOKEN"

观察日志：应显示 Gateway started 且无 Unknown model 报错。

终端 B (启动 TUI 交互):

bash 复制代码

export OPENCLAW_GATEWAY_TOKEN="YOUR_GATEWAY_TOKEN"
npx openclaw tui --token "YOUR_GATEWAY_TOKEN"

如果看到 Wake up, my friend! 并且能正常对话，说明配置成功！

📚 常用命令备忘

bash 复制代码

# 查看服务状态
openclaw gateway status

# 查看实时日志
openclaw logs --follow

# 打开 Web 控制台
openclaw dashboard

# 修改配置（推荐用 nano）
nano ~/.openclaw/openclaw.json

# 重启 Gateway
openclaw gateway restart

# 运行诊断
openclaw doctor

# 查看当前配置
openclaw config list

💡 给开发者的建议

首选 OpenAI 兼容模式 ：

对于任何兼容 OpenAI 接口的第三方模型（如 DeepSeek, Moonshot, Zhipu, MiniMax），在 OpenClaw 中优先尝试配置为 openai provider。通常比专用的 provider 实现更稳定，坑更少。
显式胜过隐式 ：

在 agent 配置中，永远使用 provider/model-id 的全限定格式 （如 openai/deepseek-chat），不要让系统去猜，避免触发奇怪的 Fallback 逻辑。
关注日志关键词：
- Unknown model ➡️ 配置错误或路由未找到。
- Falling back ➡️ 触发了系统的自动修正逻辑（通常是坏事，需警惕）。
- billing error / rate limit ➡️ 恭喜，这说明配置已成功，只是账号余额或限流问题。

总结：

OpenClaw 是个好东西，就是有点"小脾气"。摸清它的秉性，绕过那几个坑，就能愉快地玩耍啦～

核心要点：

用 WSL2 安装最稳
DeepSeek 通过 OpenAI 选项接入
必须显式指定 openai/deepseek-chat
配置文件要"极简"

有什么问题欢迎评论区交流！👇

#OpenClaw #DeepSeek #AI #LLM #WSL2 #Linux #开发者 #避坑指南 #大模型应用

OpenClaw 2026.3.8 + DeepSeek 配置实战：从“Unknown Model”到完美运行的避坑指南

📑 目录

📅 背景与环境

🤔 模型选择：为什么最后选了 DeepSeek？

🛠️ 快速安装流程 (WSL2)

1. 安装 WSL2 与 Ubuntu

2. 一键安装 OpenClaw

3. 初始化配置

⚠️ 遇到的"拦路虎" (踩坑复盘)

❌ 困难一：JSON Schema 校验过于严格

❌ 困难二：强制的"模型名重写"逻辑 (最顽固的 Bug)

✅ 最终解决方案：OpenAI "伪装"法

核心配置步骤

1. 认证配置 (Auth)

2. 模型配置 (Models) - 关键！

3. Agent 默认模型 (Agents) - 最关键的一步！

4. 完整配置文件示例 (openclaw.json)

🚀 验证与启动

📚 常用命令备忘

💡 给开发者的建议

4. 完整配置文件示例 (`openclaw.json`)