摘要：本文记录了在 Windows WSL2 (Ubuntu) 环境下部署 OpenClaw 2026.3.8 并接入 DeepSeek 模型的全过程。重点复盘了配置校验严格、模型名强制重写（Anthropic Fallback）以及 Provider 匹配陷阱两大核心问题，并给出了基于“OpenAI 兼容模式”的最终解决方案。
- 背景与环境
- 快速安装流程 (WSL2)
- 遇到的“拦路虎” (踩坑复盘)
- 最终解决方案：OpenAI “伪装”法
- 验证与启动
- 常用命令备忘
- 给开发者的建议
随着本地大模型应用的兴起，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" "
原因分析：
OpenClaw 的配置文件校验极其严格，遵循严格的 JSON Schema，不支持任何非标准定义的额外字段。
💡 教训：配置文件必须“极简”，只保留官方文档明确列出的字段。
现象：
即使将 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 交互):
如果看到 并且能正常对话，说明配置成功！
- 首选 OpenAI 兼容模式：
对于任何兼容 OpenAI 接口的第三方模型（如 DeepSeek, Moonshot, Zhipu, MiniMax），在 OpenClaw 中优先尝试配置为 provider。通常比专用的 provider 实现更稳定，坑更少。
- 显式胜过隐式：
在 配置中，永远使用 的全限定格式（如 ），不要让系统去猜，避免触发奇怪的 Fallback 逻辑。
- 关注日志关键词：
- ➡️ 配置错误或路由未找到。
- ➡️ 触发了系统的自动修正逻辑（通常是坏事，需警惕）。
- / ➡️ 恭喜，这说明配置已成功，只是账号余额或限流问题。
总结：
OpenClaw 是个好东西，就是有点”小脾气”。摸清它的秉性，绕过那几个坑，就能愉快地玩耍啦～
核心要点：
- 用 WSL2 安装最稳
- DeepSeek 通过 OpenAI 选项接入
- 必须显式指定
- 配置文件要”极简”
有什么问题欢迎评论区交流！👇
#OpenClaw #DeepSeek #AI #LLM #WSL2 #Linux #开发者 #避坑指南 #大模型应用
版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容，请联系我们，一经查实，本站将立刻删除。
如需转载请保留出处：https://51itzy.com/kjqy/228595.html