1. OpenClaw 接入 DeepSeek 官方 API 的完整配置场景
OpenClaw 是一个本地优先的 AI 客户端，支持通过models.providers结构挂载多家模型服务。它本身不绑定任何厂商，你填什么 Base URL、什么 Key、什么模型 ID，它就调什么。这次要解决的核心问题是：在 OpenClaw 里同时启用 deepseek-chat 与 deepseek-reasoner 两个模型，并且让对话链路和推理链路都能正常跑通。
适合谁看？三类人最需要这篇：一是已经在用 OpenClaw 但只配了 OpenAI 或 Anthropic，想追加 DeepSeek 的；二是刚装好 OpenClaw，第一次手动编辑openclaw.json的；三是之前配过但模型下拉菜单不显示、或者发消息报 401 的。这三种情况我都会在后面的排障章节里逐一覆盖。
DeepSeek 官方 API 的入口是https://api.deepseek.com，协议兼容 OpenAI 的 completions 格式，所以在 OpenClaw 里把api字段写成openai-completions就能对接。两个模型的区别很直接：deepseek-chat是非思考模式，响应快、适合日常问答和代码补全；deepseek-reasoner是思考模式，会先输出推理过程再给结论，适合数学推导、复杂逻辑拆解、多步规划。两者上下文窗口都是 128K，但最大输出不同——chat 侧我建议设 8192，reasoner 侧可以放到 32768，留足推理链的空间。
配置文件路径三平台统一：~/.openclaw/openclaw.json。Mac 和 Linux 直接在终端cd ~/.openclaw就能看到，Windows 在C:\Users\你的用户名\.openclaw\openclaw.json。这个文件是 JSON 格式，结构上有一个硬性要求：providers必须包在models对象里面，不能把providers直接放到根层级。我见过太多人因为少包这一层，导致模型列表整个不加载。
还有一个容易踩的坑：如果你之前已经配过其他 provider，比如 OpenAI 或某个兼容端点，不要用新内容覆盖整个文件，而是在原有providers对象里追加一个DeepSeek键，用英文逗号和前一个 provider 隔开。JSON 对逗号极其敏感，多一个少一个都会导致解析失败，而 OpenClaw 在解析失败时往往不会给明确报错，只是模型列表空白。
下面这张表先把关键参数对齐，后面配置片段直接照抄即可：
| 参数 | 取值 | 说明 |
|---|---|---|
| baseUrl | https://api.deepseek.com | 官方入口，不要加 /v1 |
| api | openai-completions | OpenClaw 专用协议标识 |
| id | deepseek-chat / deepseek-reasoner | 模型唯一标识 |
| contextWindow | 128000 | 官方确认 128K |
| maxTokens | 8192 / 32768 | chat 与 reasoner 分别设置 |
| reasoning | false / true | reasoner 必须为 true |
| input | ["text"] | 当前主力模型为纯文本 |
把这张表记住，后面无论你是手动改 JSON 还是用模板，参数来源都是它。接下来进入前置准备，也就是拿到一个可用的 API Key。
2. TaoToken 前置准备与 DeepSeek API Key 获取
在动配置文件之前，先把两件事做完：确认 OpenClaw 能正常启动，以及拿到一个有效的 DeepSeek API Key。这两步任何一步缺失，后面都会卡住。
OpenClaw 的安装这里不展开，假设你已经能打开客户端主界面。判断标准很简单：启动后能看到模型选择下拉菜单，哪怕里面是空的。如果连界面都起不来，先去把安装问题解决，配置文件的修改对它没有意义。
DeepSeek API Key 的获取流程：访问 DeepSeek 开放平台，用邮箱注册并完成验证，登录后进入控制台。左侧菜单找到 API Keys，点击创建新 Key，起个名字比如openclaw-test，创建后立即复制——Key 只显示一次，关掉弹窗就再也看不到完整值了。Key 以sk-开头，长度较长，建议直接存进密码管理器，不要贴在聊天记录或公开仓库里。
这里要提醒一个安全边界：API Key 等同于账户凭证，泄露后别人可以消耗你的额度。配置文件openclaw.json属于本地文件，不要把它提交到 Git 仓库，也不要把带 Key 的截图发到公开社区。如果你需要多设备同步配置，把 Key 抽成环境变量是更稳妥的做法，但 OpenClaw 当前版本对apiKey字段直接读字符串的支持最稳定，环境变量注入需要额外处理，新手先用直接填写的方式跑通，再考虑进阶。
如果你除了 DeepSeek 还想接入其他模型做对比测试，TaoToken 提供了一个统一的接入入口，Base URL 是https://taotoken.net/api，可以在同一个客户端里管理多家模型的 Key 和端点。它的控制台地址是 console，API Key 管理在 api-keys。不过本篇的主角是 DeepSeek 官方 API，TaoToken 只作为你后续扩展时的备选路径，不混进本次配置。
拿到 Key 之后，先别急着写进配置文件。建议先用一条 curl 命令验证 Key 本身是否有效，这样能把「Key 问题」和「配置问题」提前分离：
curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "deepseek-chat", "messages": [{"role": "user", "content": "回复两个字：收到"}], "max_tokens": 16 }'如果返回 JSON 里choices[0].message.content有内容，说明 Key 和网络都正常，问题只会出在 OpenClaw 配置层。如果这里就报 401，先检查 Key 是否复制完整、有没有多余空格。这一步花两分钟，能省掉后面大量来回排查。
3. 可复制配置：openclaw.json 中 deepseek-chat 与 deepseek-reasoner 的 JSON 片段
现在打开~/.openclaw/openclaw.json。推荐用 VS Code 或任何带 JSON 语法高亮的编辑器，不要用记事本，因为记事本容易引入不可见字符，也会让括号匹配变得困难。
先看清楚现有结构。如果你的文件里已经有models.providers，找到providers这个对象，在它内部追加DeepSeek键。如果文件是全新的，直接按下面的完整结构写。核心原则：providers外面必须包一层models。
下面这段是可直接复制的完整片段，把sk-XXXXXXXXXXXXXXXXXXXXXXXX替换成你自己的 Key：
{ "models": { "providers": { "DeepSeek": { "baseUrl": "https://api.deepseek.com", "apiKey": "sk-XXXXXXXXXXXXXXXXXXXXXXXX", "api": "openai-completions", "models": [ { "id": "deepseek-chat", "name": "DeepSeek-V3.2 (非思考模式)", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000, "maxTokens": 8192 }, { "id": "deepseek-reasoner", "name": "DeepSeek-V3.2 (思考模式 / R1)", "reasoning": true, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000, "maxTokens": 32768 } ] } } } }如果你原来已经有其他 provider，比如文件里已经有一个"OpenAI": { ... }，那么把"DeepSeek": { ... }整个对象追加到它后面，中间用英文逗号分隔。结构变成这样：
{ "models": { "providers": { "OpenAI": { "baseUrl": "https://api.openai.com/v1", "apiKey": "sk-原有Key", "api": "openai-completions", "models": [] }, "DeepSeek": { "baseUrl": "https://api.deepseek.com", "apiKey": "sk-你的DeepSeekKey", "api": "openai-completions", "models": [ { "id": "deepseek-chat", "name": "DeepSeek-V3.2 (非思考模式)", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000, "maxTokens": 8192 }, { "id": "deepseek-reasoner", "name": "DeepSeek-V3.2 (思考模式 / R1)", "reasoning": true, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }, "contextWindow": 128000, "maxTokens": 32768 } ] } } } }几个字段必须说清楚。baseUrl用https://api.deepseek.com，不要加/v1，DeepSeek 官方入口不带这个后缀，加了会 404。api字段固定openai-completions，这是 OpenClaw 识别协议类型的标识，写错会导致请求发不出去。reasoning字段是区分两个模型行为的关键：deepseek-chat设false，deepseek-reasoner设true，OpenClaw 会根据这个字段决定是否展示推理过程。
cost字段我暂时填 0，目的是先跑通链路，避免因为计费字段格式问题干扰调试。等你确认两个模型都能正常回复后，再按官方定价填入真实值。DeepSeek 官方当前定价大致是输入 Cache Miss 每百万 token 0.28 美元、Cache Hit 0.028 美元、输出 0.42 美元，具体以官网最新页面为准，填入时单位对齐 OpenClaw 的美元/百万 token 约定。
maxTokens的取值有讲究。deepseek-chat我设 8192，日常对话和代码补全够用；deepseek-reasoner设 32768，因为推理链本身会消耗大量输出 token，设太小会导致推理被截断、结论不完整。contextWindow两个都填 128000，这是官方确认的上下文窗口。
保存文件后，先别重启。用编辑器的 JSON 校验功能或在线校验工具过一遍，确认没有语法错误。JSON 不允许尾随逗号，不允许注释，所有键必须双引号包裹。这一步做扎实，能避免后面「模型不显示」的玄学问题。
4. 验证请求：对话链路与推理链路的实际测试动作
配置保存后，完全重启 OpenClaw。不是刷新页面，是关闭进程再重新打开。重启后打开模型选择下拉菜单，应该能看到两个新条目：DeepSeek-V3.2 (非思考模式)和DeepSeek-V3.2 (思考模式 / R1)。如果只看到一个或一个都没有，先跳到第 5 节排障。
验证分两条链路，分别测。
对话链路验证：新建聊天，模型选DeepSeek-V3.2 (非思考模式)，发送一条简单消息，比如「用一句话解释什么是递归」。预期结果是快速返回一段文字，没有额外的推理过程展示。如果返回正常，说明deepseek-chat的 Base URL、Key、协议三项都对。
推理链路验证：新建另一个聊天，模型选DeepSeek-V3.2 (思考模式 / R1)，发送一道需要多步推理的题，比如「一个水池有两个进水管和一个出水管，甲管单独注满需 6 小时，乙管需 8 小时，出水管排空需 12 小时，三管同时开，多久注满？」预期结果是先出现一段推理过程（可能折叠或展开显示，取决于 OpenClaw 版本），然后给出最终答案。如果只返回答案没有推理过程，检查reasoning字段是否确实设为true。
如果你想在命令行层面再确认一次推理模型的行为，可以直接用 curl 打 reasoner 端点：
curl https://api.deepseek.com/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的Key" \ -d '{ "model": "deepseek-reasoner", "messages": [{"role": "user", "content": "3 个连续奇数的和是 27，求这三个数"}], "max_tokens": 2048 }'返回 JSON 里除了choices[0].message.content，reasoner 模型通常还会带reasoning_content字段，里面是推理链。OpenClaw 在reasoning: true时就是读取这个字段来展示思考过程的。如果你在 OpenClaw 里看不到推理展示，但 curl 能看到reasoning_content，那问题在客户端渲染层，不在配置。
两条链路都跑通后，建议做一次压力验证：在同一个聊天里连续发 5 到 10 轮消息，观察是否有中途报错。有些配置问题不会在第一条消息暴露，而是在多轮上下文累积后才出现，比如 token 超限或流式解析异常。多轮测试能提前发现这类隐患。
验证通过后，回到配置文件把cost字段填上真实值，这样 OpenClaw 的费用统计才有意义。填完后再次重启，确认模型仍正常加载。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节按真实报错逐条对照。这些错误我都在不同环境里遇到过，处理方式直接给。
401 Unauthorized / Invalid API Key。最常见。三个检查点：第一，Key 是否完整复制，sk-后面有没有漏字符，前后有没有空格；第二，apiKey字段的值是否被引号正确包裹；第三，Key 是否已过期或被删除。用第 2 节的 curl 命令单独测 Key，如果 curl 也 401，问题在 Key 本身，不在 OpenClaw。
local proxy failed / connection refused。这个报错说明 OpenClaw 尝试连接baseUrl时失败。检查baseUrl是否写成https://api.deepseek.com，有没有误加/v1或结尾斜杠。另外确认本机网络能正常访问该域名，用curl -I https://api.deepseek.com看是否返回 HTTP 响应头。如果本机有网络层拦截，需要先解决网络可达性，配置层面无法绕过。
reading 'choices' of undefined / Cannot read properties of undefined。这个报错通常意味着返回的 JSON 结构里没有choices字段，OpenClaw 解析时拿到 undefined。原因可能是：api字段写错，导致请求发到了不兼容的端点；或者baseUrl指向了一个返回错误页面的地址。检查api是否为openai-completions，baseUrl是否为官方入口。还有一种情况是 Key 无效时服务端返回了错误 JSON，也会触发这个报错，所以先排除 401。
OAuth / authentication failed。OpenClaw 某些版本对需要 OAuth 的 provider 有专门流程，但 DeepSeek 官方 API 用的是 Bearer Key，不走 OAuth。如果你看到 OAuth 相关报错，检查是不是把 DeepSeek 配置写进了需要 OAuth 的 provider 块里，或者api字段被误设成了其他协议类型。DeepSeek 这条链路只需要apiKey字段，不需要额外认证配置。
模型不显示在下拉菜单。JSON 语法错误是首要嫌疑。用校验工具过一遍，重点看括号匹配和逗号。其次是providers层级写错，比如把providers放到了根层级而不是models里面。第三是models数组为空或格式不对。逐项对照第 3 节的完整片段。
reasoner 模型回复被截断。检查maxTokens是否设得太小。推理链会占用大量输出 token，8192 对复杂推理可能不够，建议 reasoner 侧保持 32768。如果仍然截断，可能是问题本身超出模型能力范围，换一个更聚焦的提问方式。
多轮对话后报错。检查contextWindow是否设为 128000。如果设小了，多轮累积会触发超限。另外确认 OpenClaw 的上下文管理策略，部分版本会在接近窗口上限时自动截断历史，如果截断逻辑和模型不匹配也可能报错。
排障的核心思路是分层：先用 curl 验证 Key 和网络，再验证配置文件语法，最后验证 OpenClaw 的加载和渲染。每一层单独确认，不要混在一起猜。
如果你在排障过程中需要对照更多接入细节，接入文档在 doc，API Key 管理在 api-keys。这些是 TaoToken 侧的入口，和 DeepSeek 官方配置不冲突，作为你后续扩展其他模型时的参考。
6. 长期编码与 Agent 场景下的模型选择建议
两个模型都跑通之后，实际用起来怎么选？我的经验是按任务类型分流。
日常编码补全、代码解释、文档问答、快速改写，用deepseek-chat。它的响应延迟低，输出直接，不产生推理链的额外 token 消耗，适合高频交互。你在 OpenClaw 里写代码时，如果每次补全都等推理过程，体验会很割裂。
复杂算法设计、多步重构规划、数学推导、需要权衡多个方案的架构决策，切到deepseek-reasoner。它先推理再回答的特性，在这类任务上准确率明显更高。代价是响应慢、token 消耗大，所以不要拿它做简单问答。
如果你在 OpenClaw 里跑 Agent 类工作流，比如让模型自主调用工具、多轮规划再执行，deepseek-reasoner更适合做规划节点，deepseek-chat适合做执行节点。这种混合用法需要在工作流配置里分别指定模型 ID，OpenClaw 支持在节点级别覆盖模型选择。
长期使用的话，建议把cost字段填准，这样 OpenClaw 的费用面板能给你真实的消耗反馈。根据反馈调整模型分配策略，把高频低复杂度任务压到 chat 侧，把 reasoner 留给真正需要深度推理的场景。这样既保证效果，又控制成本。
如果你后续想接入更多模型做横向对比，或者需要统一管理多家 API Key，TaoToken 的 Coding Plan 提供了面向长期编码场景的接入方案，模型对话入口在 模型对话。这些入口和本篇的 DeepSeek 官方配置是并列关系，你可以按需选用。
配置这件事，跑通一次之后就是模板。把第 3 节的 JSON 片段存好，下次加新模型只需要复制对象、改id、name、reasoning、maxTokens四个字段。DeepSeek 后续如果发布新模型，也是同样的追加方式。
