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 ()
• API Compatibility: OpenAI Compatible

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

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

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

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

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

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

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

运行 启动向导。

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

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

现象 ：

试图在 的 定义中添加 字段做备注时，Gateway 直接报错，提示”Unrecognized key: “description” “

原因分析 ：

现象 ：

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

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

结果导致路由表找不到 的实现，报 。

关键日志证据：

原因分析 ：

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

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

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

请编辑 文件，参考以下配置：

1. 认证配置 (Auth)

将默认 provider 设为 。

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

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

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

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

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

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

终端 A (启动 Gateway):

观察日志：应显示 且无 报错。

终端 B (启动 TUI 交互):

如果看到 并且能正常对话，说明配置成功！

1. 首选 OpenAI 兼容模式 ：

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

2. 显式胜过隐式 ：

   在 配置中，永远使用 的全限定格式 （如 ），不要让系统去猜，避免触发奇怪的 Fallback 逻辑。

3. 关注日志关键词：
   • ➡️ 配置错误或路由未找到。
   • ➡️ 触发了系统的自动修正逻辑（通常是坏事，需警惕）。
   • / ➡️ 恭喜，这说明配置已成功，只是账号余额或限流问题。

总结：

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

核心要点：

1. 用 WSL2 安装最稳
2. DeepSeek 通过 OpenAI 选项接入
3. 必须显式指定
4. 配置文件要”极简”

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

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