OpenClaw更换DeepSeek API Key完整指南：从配置到避坑

1. 为什么必须换 KeyOpenClaw 里 DeepSeek 的接入逻辑1.1 先看 OpenClaw 是怎么用 DeepSeek 的前阵子 OpenClaw 日志里开始接连出现 401 和 429看一眼就知道 DeepSeek 的 API Key 该换了。这事听起来简单但真上手换一遍你可能会发现要么找不到配置写在哪儿要么改完重启不生效要么在 WSL2 环境下服务直接起不来。这篇就是我把 OpenClaw 里 DeepSeek API Key 完整轮换一遍的记录从为什么必须换、配置文件在哪、怎么改、怎么验证到换完 Key 后最容易踩的几个坑一次性讲清楚。适合所有用 OpenClaw 接入 DeepSeek 的用户参考不管你是 Linux 部署、Windows 部署还是加了 Nginx 转发。OpenClaw 本质上是一个把大模型能力封装成“可用工具”的框架它自己不带模型所有对话、技能、工具调用都要靠接入的大模型来算。你现在用 DeepSeek就是把 OpenClaw 的推理请求转发给 DeepSeek 的 API 接口OpenClaw 拿着你的 apiKey 去请求 DeepSeek 的服务器。这个 apiKey 相当于一把钥匙DeepSeek 的服务器每次收到请求时都会先验证钥匙是否有效、余额够不够、有没有权限访问对应模型。一旦钥匙过期、被删除、密钥错误或者余额不足OpenClaw 的日志里就会出现 401 Unauthorized 或 429 Too Many Requests。我第一次遇到这类报错时第一反应还以为 OpenClaw 服务挂了后来进日志一看连着几十条 authentication failed才意识到是 Key 的问题。所以遇到 OpenClaw 突然不可用、对话框一直报网络错误时先不要急着重启先看日志里有没有 401 的痕迹。1.2 什么情况下必须换 Key换 Key 不一定是 Key 有问题也可能是你需要主动轮换。我整理了最常见的四类情况余额耗尽DeepSeek 是按 token 计费的产品一旦账户余额为 0服务端会直接拒绝请求报 402 或 403这时候只要充值即可Key 本身不用换。但如果你担心旧 Key 的扣费记录混乱或者不想让某个 Key 挂在已经不用的项目上也可以选择重新生成 Key。密钥泄露Key 一旦被贴到公共仓库或者截图发到群里对方就能借用你的额度。DeepSeek 的 Key 是明文凭证没有额外交易密码别人拿到就能直接调用所以遇到泄露时最稳妥的做法就是立刻删除旧 Key同时生成一个新 Key。账号迁移或重新注册当你从 A 账号切到 B 账号时A 账号的 Key 自然就失效了必须在 B 账号下重新创建 Key 并更新配置。模型版本切换或平台策略调整DeepSeek 官方偶尔会调整模型名称、接口版本或密钥前缀规则如果你的 OpenClaw 配置里写死了旧的 API 路径或旧 Key 格式也要跟着改。这里有一个经常被忽略的点DeepSeek 平台上的 Key 创建之后只能看一次完整明文之后平台就只显示掩码。所以你换完 Key 后一定要先把新 Key 保存到一个安全的位置再继续操作不然再过五分钟回来找就找不到了。我自己踩过一次这个坑换完 Key 忘了存重启 OpenClaw 时才想起来已经看不到明文了只能再生成一次。1.3 换 Key 前先做风险检查动手之前我建议先做三件准备工作能省掉后面一大堆麻烦。第一备份现有配置把 config.yaml、.env 以及 systemd 服务文件复制到带时间戳的备份目录万一改错了能快速回滚。第二确认自己当前实际生效的配置路径不要凭记忆乱猜用 openclaw config path 或 openclaw doctor 这类命令查清楚。第三排查是否有多个 OpenClaw 实例在跑比如 WSL 里一个、Windows 侧一个或者 Docker 容器里一个。你可以用 ps aux | grep openclaw 和 docker ps 两条命令快速看清现状。这三件事如果之前没做你很可能在改完一个配置后发现另一个实例还在用旧 Key又得从头排障。另外注意在修改前记录旧 Key 的前几位和后四位有些排障场景需要对照日志里的掩码信息没有这个记录你连新旧都分不清。2. OpenClaw 里 DeepSeek 的配置到底写在哪儿2.1 配置文件openclaw.config.yaml / config.json / .envOpenClaw 的配置设计比较灵活支持 YAML、JSON 和 .env 三种方式目的是适应不同部署习惯。大多数 Linux 部署者习惯用 config.yamlWindows 新手用户则容易被 .env 吸引因为看起来更简单。但不管用哪个最终 OpenClaw 都会把配置合并到内存里形成一个统一的配置对象加载顺序大概是默认配置优先度最低配置文件次之环境变量更高命令行参数最高。常见的 DeepSeek 相关配置项是 llm.providerdeepseek、llm.api_basehttps://api.deepseek.com、llm.api_keysk-xxx、llm.modeldeepseek-chat 或 deepseek-reasoner还有 llm.max_tokens、llm.temperature 等参数。如果你是在 Ollama 或 vLLM 上跑的本地模型那么 provider 可能是 ollama 或 openaiapi_base 指向 127.0.0.1:11434 或 8000这种情况下其实不需要 DeepSeek 的 Key。很多人会把“OpenClaw 需要 DeepSeek Key”和“DeepSeek 模型通过 Ollama 在本地运行”这两件事搞混。本地跑的模型找的是本地服务OpenClaw 调用它时配置的是本地 api_base只有当你把推理请求发到 DeepSeek 的云端接口时才需要 DeepSeek 的 apiKey。2.2 环境变量的优先级与常见混用问题我之所以强调看配置位置是因为 OpenClaw 有超过一半的“改 Key 不生效”案例都出在优先级上。比如你在 config.yaml 里改了 api_key但你的 .bashrc 或 .zshrc 里早就 export 了 DEEPSEEK_API_KEYsk-old那么 OpenClaw 启动时环境变量的值会把配置文件里的新 Key 覆盖掉日志里看起来还是旧 Key。反过来也一样如果你只改了环境变量但 OpenClaw 默认加载的 config.yaml 里还写着旧的明文可能也会有问题。所以要换 Key 时不要只改一处先跑一条命令确认自己的环境变量里有没有残留。Linux/macOS 可以用 env | grep -i deepseek 来查看Windows PowerShell 用 Get-ChildItem Env: | Where-Object { $_.Name -like DEEPSEEK }。查完再改配置文件改完重启服务之前再 export 一次或者在启动脚本里同步更新避免两套配置打架。如果确实想让 Key 只出现在环境变量里最干净的做法是在 OpenClaw 的启动脚本中统一写 export DEEPSEEK_API_KEY新Key并用命令行参数明确指定 API Key 读取方式保证启动时只加载一套配置。2.3 借助日志和状态命令确认当前 KeyOpenClaw 提供了一个类似 doctor 的检查命令一般叫 openclaw doctor 或 openclaw check它会把当前使用的 provider、api_base、模型名称、API Key 前几位显示出来。你用它在换 Key 前后各跑一次就能快速对比。另外启动日志里通常会有一行类似 Using provider: deepseek, model: deepseek-chat, endpoint: https://api.deepseek.com 的输出如果 endpoint 不对那问题可能就不在 Key 上而在 api_base 上。注意OpenClaw 的日志不会直接打印完整 Key只打印掩码这是正常的倒不用慌张。如果显示的是空或者 masked invalid再去检查配置文件是否被某些校验规则拦截了。这个命令很轻量建议养成习惯每次改完配置都跑一次日志和 doctor 输出都正常了再继续下一步。3. 更换 DeepSeek API Key 的完整实操步骤3.1 在 DeepSeek 开放平台创建新 Key第一步是去 DeepSeek 开放平台登录账号进入 API Keys 管理页面点击“创建 API Key”或“新建密钥”。为了让后续运维更清楚我建议给 Key 起一个能识别用途和时间的名字比如 openclaw-prod-202505 或 openclaw-home这样在多个 Key 并存时方便排查。DeepSeek 平台一般会区分开发环境和生产环境或者让你填写 Key 描述选好后确认创建。创建完成后页面会显示一次完整的 Key格式一般是 sk- 开头的一长串字符。此时要立刻复制并保存到密码管理器比如 Bitwarden、KeePass或者至少放在一个权限设为 600 的本地文件里。保存好之后再点关闭因为很多平台关闭弹窗后就再也看不到明文了。复制时可以用鼠标精确选择避免多复制了空格格式问题会引起后面无数次的 401。关于 Key 的额度提醒创建新 Key 后旧 Key 并不会立刻被平台主动通知 OpenClawOpenClaw 只有等到下一次请求时才可能收到 401所以不用担心旧 Key 还没失效会冲突。但如果旧 Key 已经泄露我建议回到 API Keys 页面把旧 Key 立即删除而不是留着备用因为攻击者可能仍在持续盗刷你的额度。3.2 修改 OpenClaw 配置并重启服务拿到新 Key 后按顺序做下面这五件事停止 OpenClaw 服务。如果用的是 systemd执行 sudo systemctl stop openclaw否则直接 CtrlC 终止前台进程。这一步很多人会忽略以为改配置不用停服务但 OpenClaw 通常只在启动时读取配置哪怕你改了配置运行中的进程也不会自动重载。用文本编辑器打开你实际生效的配置文件。如果不知道是哪一份先用 openclaw config path 或 openclaw doctor 查看实际路径不要靠猜。最常见的位置是 ~/.openclaw/openclaw.config.yaml也有可能是 /etc/openclaw/config.yaml。找到 llm.api_key 一行把旧值替换成新 Key。如果使用的是 .env 方式就修改 DEEPSEEK_API_KEY 这一行。注意 YAML 里 Key 值如果包含特殊字符比如 # 或空格要用引号把整个值包起来写成 api_key: sk-xxx否则 YAML 解析时会把井号当成注释符导致值被截断。清理环境变量残留。如果你之前用 export 或者启动脚本设置过 DEEPSEEK_API_KEY现在也一起改掉。改完 Bash 里执行 export DEEPSEEK_API_KEY新KeyPowerShell 里执行 $env:DEEPSEEK_API_KEY新Key。重新启动 OpenClaw并盯住启动日志前十几行确认没有 ERROR 级别的报错。这里补充一个关于 Windows 环境的小提示热词里提到的 WSL2 场景很常见。如果你在 WSL 里跑 OpenClaw而 Windows 侧还有一个 OpenClaw.Win 或 companion 进程两边可能各自维护一份配置。改 WSL 内的配置只是第一步Windows 侧如果有独立配置也要同步改否则 Windows 侧的客户端走自己的 Key依然会 401。我在实际排障时就遇到过这种情况任务卡了半小时最后发现是两个配置各管各的。3.3 验证用 curl 与日志确认新 Key 生效改完配置未必代表“Key 已经生效”必须做两层验证。第一层验证是直接测试 DeepSeek 接口。在终端执行curl https://api.deepseek.com/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的新Key \ -d {model:deepseek-chat,messages:[{role:user,content:hello}],max_tokens:10}如果返回 JSON 里带 id、choices 和 usage 字段说明这个 Key 本身能用并且网络是通的。如果返回 401说明 Key 复制有问题或已被平台禁用如果返回 402/403说明是余额或权限问题如果一直超时说明 api_base 或网络链路可能有问题。第二层验证是看 OpenClaw 自己的日志。重启服务后用 tail -f ~/.openclaw/logs/openclaw.log 实时查看日志Windows 下对应目录可能是 %USERPROFILE%.openclaw\logs。看到类似 deepseek api key loaded: Ok 或者 auth ok 这样的日志说明 OpenClaw 已经认领了新 Key。之后随便在对话框里发一条消息让它真正调用一次 DeepSeek确认整条链路都通。我习惯把这两步连起来做先 curl 再日志能立刻定位是 Key 本身的问题还是 OpenClaw 配置的问题。如果 curl 成功但 OpenClaw 还是 401那八成是环境变量覆盖了配置文件回到 2.2 节的检查思路。3.4 有 Nginx 或 API 网关时的特殊处理热词里提到 Nginx 转发 Ollama 设置 apiKey这种情况在自建环境里太常见了。很多人会通过 Nginx 把 https://api.deepseek.com 转发到某个内网地址或者把 Ollama 的 11434 端口暴露给局域网。如果你也这么干换 Key 后要注意三件事。首先Nginx 转发的是 API 请求头它本身不校验 Key所以 Key 永远只在源站生效。OpenClaw 配置里 api_base 指到你的 Nginx 地址时Nginx 把 Authorization 头原样透传给上游所以真正要改的还是 OpenClaw 里的 api_key不是 Nginx 配置。其次如果 Nginx 层做了 auth_request 拦截比如用 openresty 或 lua 脚本统一加固定 Header那 OpenClaw 的 Key 可能根本没被透传这种情况下 401 可能与 Key 无关而是网关规则问题。排查时可以直接临时绕开 Nginx让 OpenClaw 直连官方 API看是否正常以此判断问题出在数据链路哪一环。最后如果你用 vLLM 本地部署 DeepSeek 模型其实只有 api_base 是本地地址Key 可以随便填一个占位符vLLM 默认不校验 Key。这个跟云端 DeepSeek 不同别搞混。4. 换 Key 后的常见问题与排查记录4.1 WSL2 环境下服务起不来的处理这次换 Key 过程中排在最前面的坑是 WSL2 环境问题。很多人都是在 PowerShell 里用 wsl --status 看到的提示环境没有正确运行或者没有配置默认版本导致 OpenClaw 启动时连不上内网服务。这个问题的本质是 WSL 2 和 WSL 1 的差异OpenClaw 的某些依赖依赖 Linux 内核特性必须运行在 WSL 2 模式下。当你在 PowerShell 中执行 wsl --status如果看到“WSL 版本1”或者类似信息先执行 wsl --set-version 发行版名称 2把发行版升级到 WSL 2。升级耗时可能比较久但完成后 OpenClaw 一般就能正常起来。另外如果你修改过 /etc/resolv.conf 或 hosts 文件重启 WSL 后这些配置可能被重置导致 OpenClaw 访问 DeepSeek API 时连接超时。排查时可以先用 wget 或 curl 测试一下网络连通性能通再考虑 Key 的问题。这类问题看起来像是换 Key 引起的实际上和 Key 一点关系都没有别在平台上反复生成新 Key 浪费时间。4.2 日志里始终显示旧 Key这个问题的根因我在 2.2 节讲过但实际现场比理论更隐蔽。我遇到过一种情况配置文件里确实已经换成新 Key 了但 OpenClaw 启动时加载的是一个备份配置因为 systemd 服务文件里指定的路径是 -c /opt/openclaw/backup/config.yaml而你改的是 ~/.openclaw/openclaw.config.yaml。检查这种问题最直接的方式是看服务启动命令执行 ps aux | grep openclaw观察命令行里的 -c 参数指向哪个文件。如果发现用的是 systemd还可以执行 systemctl cat openclaw 查看 ExecStart 的完整内容。总之不要假设配置文件只有一个。另一个隐蔽原因是 Key 前后有换行符或空格YAML 会把值当作字符串的一部分造成实际提交的 Key 和平台上的不一样。拿编辑器打开配置文件时尽量开启显示空白字符肉眼确认一下等号或冒号后面没有多余字符。4.3 Node.js 版本过老导致 OpenClaw 无法启动OpenClaw 的安装器依赖 Node.js热词里有“node.js官网下载openclaw”说明很多人是从 Node.js 环境装的。如果你的 Node.js 版本低于项目要求OpenClaw 可能在安装时没问题但运行时报一堆模块加载错误比如 Error: Cannot find module、SyntaxError: Unexpected token 等。换 Key 时如果你顺手升级了 Node.js 版本反而可能导致兼容性问题进程无法启动。处理办法是先看 OpenClaw 文档里要求的 Node.js 版本范围然后在终端执行 node -v 对比。如果版本不对用 nvm 安装指定版本而不是直接装最新版。我之前为了省事升级到最新 Node.js 22结果 OpenClaw 某个依赖不兼容启动直接报错后来回退到 LTS 版本才恢复。换 Key 本身不影响 Node.js但如果你把“换 Key顺便升级环境”两件事一起做一旦出问题就不好定位了。建议一次只动一个变量这也是排障的基本素养。4.4 多实例、多客户端时的 Key 同步热词里还有 qwen2.5-3b 关联到 openclaw、codex 接入 deepseek 等联想说明不少用户会把 OpenClaw 和其他 AI 客户端串在一起用。这时候很容易出现一个问题你在 OpenClaw 里换了 Key但 Codex、CherryStudio 或者其他客户端还在用旧 Key。这些客户端各自保存了自己的配置OpenClaw 不可能替它们更新。所以如果你的工作流里有多个入口建议用一个统一的 Key 管理方式比如把 Key 写入一个 .env 文件然后让所有工具都引用同一份环境变量。这样以后轮换 Key 时只需要改一个文件。另外CherryStudio 这类 GUI 工具通常有自己的“设置-模型-API 密钥”界面和 OpenClaw 的配置完全独立。如果你在 OpenClaw 里改了 KeyCherryStudio 里还留着旧 Key那么在 CherryStudio 里调用 DeepSeek 时依然 401。这不算 Bug只要记得每个工具单独替换即可。4.5 遇到 429 不是 Key 的问题换完 Key 之后如果日志里开始刷 429 Too Many Requests别急着再换一次429 通常和 Key 无关而是你超过了 DeepSeek 的速率限制或并发上限。这时候可以调整 OpenClaw 的请求并发添加请求间隔或者检查是不是某个 Skill 在循环调用。如果项目支持也可以配置一个轻量级的请求缓冲层把高频请求排队。还要注意 DeepSeek 的限流分为每分钟请求次数和每分钟 token 数两档即使同一个 Key这两个指标也会单独计算。遇到 429 时看看响应头里的 Retry-After 字段按它建议的时间退避别硬怼。我在实际使用中见过有人把 429 误判成 Key 失效反反复复换了四五次 Key结果一次都没解决问题最后才发现是某个后台任务在疯狂跑模型。所以遇到 429 先看日志里的调用来源再动手。4.6 记录与自动化让下次换 Key 更快既然已经换了一次 Key我强烈建议你顺手把整个过程脚本化。最基础的做法是在 OpenClaw 的配置目录下准备一个 env.example 文件写上 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL 等变量名但不要填真实值。每次换 Key 时把旧 Key 备份到带时间戳的文件里然后写入新 Key再重启服务。更进一步可以用 systemd 的 EnvironmentFile 或者在启动脚本里读取同一个 secrets 文件这样配置文件里就不会出现任何明文 Key避免哪天把配置文件发出去导致泄露。如果团队协作也可以考虑把密钥托管到一个专门的密钥管理工具里OpenClaw 启动时通过接口拉取。这样 Key 就只是一串运行时数据而不是躺在配置文件里的静态明文。这个方法虽然前期要多花一点时间配置但长远来看能省掉大量来回改配置、排查问题的成本。我个人在实际操作中的体会是更换 DeepSeek 的 apiKey 在 OpenClaw 里并不是一个高频操作但一旦要做涉及的坑却不少。绝大多数“换完不生效”的案例都和配置加载顺序、多配置来源、环境变量残留这三件事有关只要按照先确认配置路径、再改文件、再清环境变量、最后重启验证的顺序来走基本能做到一次搞定。最后再分享一个小技巧换完 Key 后不要急着删旧 Key先在 OpenClaw 里稳定跑一两天确认新 Key 没有被限流、没有触发账号异常再回平台删除旧 Key。这样即使新 Key 有问题你还能临时切回去不至于把自己锁在门外。