DeepSeek V4 接入 OpenClaw 保姆级配置教程：API Key 与 baseUrl 一次填对

1. 先搞清楚 OpenClaw 卡在哪：baseUrl 与 API Key 的填写逻辑

OpenClaw（社区里常叫“龙虾”）是一个本地优先的 AI Agent 运行框架，它的模型配置全部落在本地一个 JSON 文件里，不走云端账号体系。这意味着你填进去的baseUrl、apiKey、model id三个值，就是它调用模型的全部凭据。很多人第一次接入 DeepSeek V4 时，装好了 OpenClaw、也能打开界面，但一发消息就报错，问题几乎都集中在这三个字段上：baseUrl多写了或漏写了/v1、apiKey前后带了空格或换行、model id写成了展示名而不是真实 ID。

这篇教程面向的就是这个卡点：本地 OpenClaw 已经装好，配置文件也找到了，但不确定baseUrl到底该填https://api.deepseek.com还是https://api.deepseek.com/v1，apiKey从哪来、怎么放才不出错，model id用 Flash 还是 Pro。我会给出可直接复制的 settings 配置片段、逐项填写对照表，以及一次最小请求验证动作，让你在改完配置后能立刻确认模型是否真的通了。

先说清楚三个参数各自的角色，后面填的时候就不会乱。baseUrl是“服务地址”，告诉 OpenClaw 把请求发到哪个域名和路径前缀；apiKey是“门禁卡”，证明你有权限调用；model id是“具体房间号”，指定你要调用的模型版本。三者缺一不可，且必须严格匹配——baseUrl决定了协议格式（OpenAI 兼容还是 Anthropic 兼容），model id必须和服务端注册的 ID 完全一致，多一个字符都会返回模型不存在。

这里有个容易踩的坑：DeepSeek 官方同时提供 OpenAI 协议和 Anthropic 协议两套入口，路径不同。OpenClaw 的api字段填的是openai-completions时，baseUrl必须走 OpenAI 协议那套；如果你把 Anthropic 协议的地址填进 OpenAI 协议的配置里，请求会直接 404 或协议解析失败。所以填之前先确认你的 provider 用的是哪种api类型，再对应选地址。

另外，如果你希望统一管理多个模型的 Key、避免在多个平台之间来回切换，也可以把 DeepSeek V4 的调用走 TaoToken 的聚合入口。它的 API 地址是https://taotoken.net/api，同样兼容 OpenAI 协议，baseUrl填这个、apiKey换成在 TaoToken 控制台创建的 Key 即可，model id仍按实际模型名填写。对本地 OpenClaw 来说，这两种方式在配置文件层面没有区别，只是baseUrl和apiKey的来源不同。下面我以官方地址为主讲配置结构，聚合入口的替换方式会在对照表里标出来。

2. 接入前的准备：拿到可用的 API Key 与确认模型 ID

在动配置文件之前，先把两样东西准备好：一个可用的 API Key，以及你要调用的模型 ID。这两样没确认就改 JSON，改完也是白改。

获取 API Key 的路径很直接。打开 DeepSeek 开放平台，登录后进入 API Keys 管理页，点创建，给 Key 起个能认出来的名字，比如openclaw-dev，确认后立即复制。这里有个硬性提醒：完整 Key 只在创建时显示一次，关掉弹窗就再也看不到，只能重新建。所以复制后先粘到一个临时文本里，确认没有截断、没有多余空格，再往配置文件里放。很多人报 401，就是因为复制时少了几位或者末尾带了个换行符。

如果你走 TaoToken 的聚合入口，流程类似：登录控制台，在 API Keys 页面创建 Key，复制保存。它的 Key 格式和官方不同，但用法一致——填进apiKey字段即可。区别在于baseUrl要换成https://taotoken.net/api，而不是 DeepSeek 官方域名。这一点在后面的对照表里会单独列一行，避免你混填。

模型 ID 这块要特别注意：配置里填的必须是服务端注册的真实 ID，不是界面上显示的名字。DeepSeek V4 目前常用的两个 ID 是deepseek-v4-flash和deepseek-v4-pro。Flash 偏速度和低成本，适合日常对话、简单代码补全、高频调用；Pro 推理更强，适合复杂架构设计、长文档分析、多步推理任务。你在 OpenClaw 里想用哪个，就把配置里所有出现模型 ID 的地方统一换成那个，包括models数组里的id、agents.defaults.model.primary、以及agents.defaults.models的键名——这三处必须完全一致，否则 OpenClaw 会找不到模型映射。

还有一个前置动作容易被忽略：确认 OpenClaw 已经完成初始化。如果你在~/.openclaw/或C:\Users\你的用户名\.openclaw\下找不到openclaw.json，说明还没初始化过。此时在命令行执行openclaw setup，它会自动生成默认配置文件，然后再进去改。别手动新建一个空 JSON，缺字段会导致启动失败。

准备工作做完，你手上应该有三样东西：一个确认无误的 API Key、一个确定的模型 ID（Flash 或 Pro）、一个确定可用的baseUrl（官方 OpenAI 协议地址或 TaoToken 聚合地址）。带着这三样再进配置文件，效率会高很多。

3. 可复制配置：openclaw.json 的 settings 片段与逐项对照

配置文件的位置按系统区分：Windows 是C:\Users\你的用户名\.openclaw\openclaw.json，Ubuntu / macOS 是~/.openclaw/openclaw.json。用 VS Code 打开，它有 JSON 语法高亮和括号匹配，能帮你避开大部分格式错误。改之前先复制一份备份，命名成openclaw.json.bak放同目录，改坏了直接还原，不用从头排查。

下面是接入 DeepSeek V4 的最小可用配置片段，你可以整段替换，也可以只改自己文件里对应的字段。注意这是 JSON，不能有注释、不能有尾逗号：

{ "models": { "mode": "merge", "providers": { "custom-001": { "baseUrl": "https://api.deepseek.com/v1", "apiKey": "sk-你的真实密钥", "api": "openai-completions", "models": [ { "id": "deepseek-v4-pro", "name": "deepseek-v4-pro (Custom Provider)", "reasoning": false, "input": ["text"], "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 } } ] } } }, "agents": { "defaults": { "model": { "primary": "custom-001/deepseek-v4-pro" }, "models": { "custom-001/deepseek-v4-pro": {} }, "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace", "contextPruning": { "mode": "cache-ttl", "ttl": "1h" }, "compaction": { "mode": "safeguard" }, "heartbeat": { "every": "30m" } } }, "gateway": { "port": 18789, "mode": "local", "bind": "loopback", "controlUi": { "allowedOrigins": ["http://localhost:18789"] }, "auth": { "mode": "token", "token": "" } } }

这段配置里真正决定能不能调通模型的，是四个字段。下面用表格逐项对照，你填的时候对着改：

几个细节值得单独说。baseUrl末尾不要加多余斜杠，https://api.deepseek.com/v1/和https://api.deepseek.com/v1在部分客户端里行为不同，统一不带尾斜杠最稳。apiKey粘贴后检查首尾，JSON 里字符串不能有裸换行。model id三处联动：models[].id、agents.defaults.model.primary、agents.defaults.models的键，改一个就得全改，否则 primary 指向的模型在 models 映射里找不到，启动时就会报模型未注册。

如果你用 Flash，把上面片段里所有deepseek-v4-pro替换成deepseek-v4-flash，包括name字段里的展示名也建议同步改，方便日后辨认。reasoning字段按模型实际能力填，不确定就保持false，不影响基础调用。cost全填 0 是本地自用场景的常见做法，不参与计费计算，填真实值也不会影响请求本身。

改完保存，别急着开界面。先做下一步的验证，确认配置在请求层面是通的，再去 UI 里试，能省掉“到底是配置错还是界面错”的来回猜。

4. 验证请求：一次最小调用确认模型真的通了

配置改完，最稳的验证方式不是直接开 OpenClaw 界面发消息，而是先用一条最小请求确认baseUrl、apiKey、model id三者组合在服务端是有效的。这样即使失败，你也能立刻定位是凭据问题还是 OpenClaw 自身问题。

用 curl 发一条 OpenAI 协议的 chat completions 请求，把地址、Key、模型 ID 换成你自己的：

curl https://api.deepseek.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的真实密钥" \ -d '{ "model": "deepseek-v4-pro", "messages": [ {"role": "user", "content": "只回复两个字：通了"} ], "max_tokens": 16 }'

如果你走 TaoToken 聚合入口，把第一行地址换成https://taotoken.net/api/chat/completions，Key 换成 TaoToken 的 Key，其余不变。注意聚合入口的路径拼接规则以控制台文档为准，/api后面接标准 OpenAI 路径。

正常返回是一个 JSON，choices[0].message.content里会有模型回复的内容，usage里能看到 token 消耗。看到这个结构，说明三要素全部正确，问题不在凭据层。如果返回 401，是 Key 无效或格式不对；返回 404，多半是baseUrl路径错了或模型 ID 不存在；返回 400 且提示 model 相关，是model id拼写问题。把这几种状态和你的实际返回对一下，基本能锁定原因。

curl 通了之后，再重启 OpenClaw。命令行里Ctrl+C停掉当前进程，重新执行启动命令（通常是openclaw start或你平时的启动方式），等 gateway 在18789端口起来，打开http://localhost:18789进控制台，在对话框里发一句简单的话，比如“用一句话解释什么是递归”。能正常流式返回，就说明整条链路通了。

这里补一个实测经验：如果 curl 通了但 OpenClaw 界面里报错，优先看 OpenClaw 的终端日志，而不是界面提示。日志里会打印实际发出的请求地址和模型 ID，你能直接看出它读的是不是你改的那份配置——有时候改错了文件路径（比如改的是备份文件），或者进程没重启读的还是旧配置，都会造成“明明改了却不生效”的假象。

验证通过后，你可以再发一个稍复杂的代码问题，感受一下 Pro 和 Flash 的差异。同一段提示词分别用两个模型 ID 跑一次，响应速度和内容深度会有明显区别，按你的实际任务类型选就行，不用纠结哪个“更好”。

5. 常见报错排查：401、local proxy failed 与 reading choices

配置和验证过程中，报错信息往往比界面提示更诚实。下面按真实遇到的报错逐条对照，每条给出触发原因和修正动作。

401 Unauthorized / invalid api key：这是最高频的一个。原因集中在三处——Key 复制不完整、Key 前后带空格或换行、用了别的平台的 Key 填进当前baseUrl。排查动作：把apiKey的值单独拿出来，用echo -n "你的key" | wc -c看长度是否符合预期，或者直接在 curl 里换一个新创建的 Key 试。如果 curl 也 401，就是 Key 本身问题，回平台重建一个；如果 curl 通、OpenClaw 报 401，检查配置文件里是不是有多份 provider、实际生效的那份 Key 没改。

local proxy failed / connection refused：这个报错通常不是模型凭据问题，而是 OpenClaw 的 gateway 没起来或端口被占。先确认gateway.port填的18789没有被别的进程占用，bind是loopback时只能本机访问，别用外部地址去连。再看终端日志里 gateway 是否成功监听。如果改过controlUi.allowedOrigins，确认里面包含你实际访问的地址，否则控制台会被拦。这个错和 API Key 无关，别在 Key 上反复折腾。

reading 'choices' / cannot read properties of undefined：这个报错说明客户端拿到了响应，但响应结构里没有choices字段，通常是服务端返回了错误 JSON（比如{"error": {...}}），而客户端仍按成功结构去读。根因还是baseUrl或model id不对——地址指向了一个不返回 OpenAI 标准结构的端点，或者模型 ID 不存在导致服务端返回错误体。排查动作：用第 4 节的 curl 原样跑一次，看返回体到底是标准结构还是 error 结构。如果是 error，按里面的 message 修正；如果 curl 正常但 OpenClaw 报这个，检查api字段是不是openai-completions，填错协议类型会导致解析路径不对。

OAuth / token 相关报错：如果你在配置里启用了需要 OAuth 的 provider，或者gateway.auth.mode设成了token但token为空，会出现鉴权类报错。本地自用场景下，gateway.auth.token留空、mode保持token一般不影响本地回环访问；但如果你改过bind或从外部访问，就需要补上 token。这类报错和模型 API Key 是两套体系，别混为一谈——前者是 OpenClaw 自身的访问控制，后者是模型服务的鉴权。

模型未注册 / model not found：三处模型 ID 不一致的典型表现。models[].id写deepseek-v4-pro，但primary写成custom-001/deepseek-v4-flash，或者agents.defaults.models的键名拼错，都会导致启动或调用时找不到模型。修正动作：全文搜索模型 ID，确保models[].id、primary的斜杠后半段、models映射的键名三处完全一致，provider 前缀custom-001也要和providers下的键名一致。

排查顺序建议固定下来：先 curl 验证凭据层，再看 OpenClaw 终端日志确认读的配置和实际请求，最后才去界面层找问题。这个顺序能避免你在 UI 上反复试错却始终没碰到根因。

6. 后续使用与入口选择：把 Key 管理和模型切换理顺

配置跑通之后，日常使用还有两件事值得理顺：Key 怎么管、模型怎么切。

Key 管理上，本地自用直接把 Key 写进openclaw.json完全可行，但要注意这个文件别随手传到代码仓库或共享目录。如果你有多个项目共用 OpenClaw，或者团队里有人要读这份配置，建议把 Key 放到系统环境变量里，配置文件里引用变量而不是明文。OpenClaw 的 provider 配置支持从环境读取，具体写法以你当前版本的文档为准，核心思路是apiKey不落明文。另外，定期在平台侧轮换 Key，旧 Key 停用，能降低泄露风险。

模型切换上，Flash 和 Pro 的取舍不用纠结太久。日常对话、简单补全、高频轻量任务用 Flash，响应快、成本低；复杂推理、长文档、多步代码任务切 Pro。切换时只改模型 ID 三处联动，baseUrl和apiKey不动。如果你同时想保留两个模型随时切，可以在models数组里放两条，agents.defaults.models里也建两个键，primary指向当前默认那个，需要时改primary即可，不用反复改数组。

入口选择上，官方地址适合只用一个模型、追求链路最短的场景；如果你同时接多个模型、希望 Key 和用量在一个地方看，走 TaoToken 的聚合入口会更省事，baseUrl换成https://taotoken.net/api，Key 在它的控制台创建，模型 ID 仍按实际填。两种方式在 OpenClaw 配置结构上完全一致，切换成本就是改两个字段。

如果你在验证阶段想快速对比不同模型的实际输出，可以直接用模型对话入口发同一段提示词，看响应差异再决定默认用哪个；长期跑编码和 Agent 任务的话，Coding Plan 这类按周期计费的方式通常比按 token 逐次调用更可控。接入文档里有各协议的地址和参数说明，配置时对照着看能少走弯路。Key 的创建和管理在控制台的 API Keys 页面，接入过程中遇到协议或路径问题，文档里的示例请求可以直接拿来和你的 curl 结果比对。