本文依据2026-11-11核对的官方文档整理,未做本地安装实测;命令与界面以对应版本为准。看到 401 或 403 时,先确认是哪一个服务返回了错误,再检查对应凭证,避免把模型 API Key 与 Gateway 的连接认证混为一谈。

第一步:记录出错的位置

保留四项信息:你刚执行的操作、错误出现的入口、发生时间,以及去掉敏感值后的错误内容。不要只截取“401”或“403”两个数字。

出错位置 优先核对的范围
打开或连接 Gateway 控制界面时 所连接的实例、地址,以及该 Gateway 的连接认证配置
Gateway 已接收消息,但调用模型失败时 模型服务商、模型引用、API Key 或登录凭证
某个消息渠道收发失败时 该渠道的账号、应用权限与对应错误记录

这张表是定位顺序,不是用状态码直接给出唯一结论。相同数字可能出现在不同服务中,不能看到 403 就立即更换模型密钥。

第二步:先看运行状态,再对照日志

官方排错文档给出的检查顺序包括:

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe

在出错时间附近观察日志,判断问题属于 Gateway 服务、模型请求还是消息渠道。logs --follow 用于持续查看日志;分享给别人前,先删除其中的 Token、API Key 和私人消息。

预期检查点:官方文档把 Gateway 状态中的 Runtime: running、成功的连接检查与 Capability: ... 行作为健康信号之一;doctor 不应报告阻断性的配置或服务问题。实际字段与版本有关,不要求你的全部输出和教程逐字相同。

第三步:如果失败的是模型调用

进一步查看:

openclaw models status

将当前模型与它所属的服务商对应起来,再核对:

  1. 凭证是否来自这个服务商的官方控制台。
  2. 密钥是否仍有效,是否在复制时带入了空白或不完整内容。
  3. 当前账号是否允许调用所选模型。
  4. 使用的是哪个凭证来源,是否与预期配置相同。

官方的 /gateway/authentication 文档虽然位于 gateway 路径下,讲的是模型服务商认证,包括 API Key 与 OAuth;它明确把 Gateway 连接认证指向另一套配置文档。因此,不能仅凭页面路径就把模型密钥当成 Gateway 登录令牌。

如果准备重新配置 DeepSeek,可以按 模型接入教程 使用对应插件与交互引导,避免在多个位置填入相互冲突的值。

常见场景:终端可用,后台进程仍认证失败

终端当前会话中的环境变量,不代表后台 Gateway 已经读取到它。官方认证文档要求将模型凭证放在运行 Gateway 的主机上,并说明 systemd/launchd 场景可以使用 ~/.openclaw/.env。

以 DeepSeek 的变量名为例,文件中的配置形式为:

DEEPSEEK_API_KEY=YOUR_API_KEY

YOUR_API_KEY 必须在自己的可信环境中替换,不能把占位符原样作为真实凭证。编辑文件时保留已有配置,不要直接覆盖整个文件;公开求助也不要上传 .env。

按官方说明,手动修改后台进程所用的凭证后,重启相应 Gateway 进程,再执行:

openclaw models status
openclaw doctor

然后只发送一条简短消息,检查相同问题是否仍会出现。不要仅凭 .env 中存在某一行就宣布认证成功。

如果失败的是 Gateway 连接

先确认自己连接的是预期实例,核对该实例当前采用的连接认证方式。模型 API Key 与 Gateway token、密码或代理认证的用途不同,不应互相替换。

这一部分应依据当前版本的 Gateway 配置说明及实际状态排查;本文不提供关闭认证或放宽代理信任的快捷修复。若需要他人协助,只提供配置字段名、认证方式和脱敏后的错误,不提供完整令牌。

修复后的验收与求助信息

每次只改一个有证据支持的问题,记录修改项,再检查运行状态并复现原来的操作。验收至少包含:原入口可以正常访问或发出请求、日志中不再出现同一失败、实际消息能够返回预期结果。

如果仍未解决,整理“运行环境、出错时间、复现步骤、当前模型或渠道、脱敏错误、已经做过的改动”。这比连续更换密钥或反复重装,更容易让下一位排查者找到问题所在。

继续阅读

参考资料与核对日期

资料核对:2026-11-11。以下为对应的官方文档入口;本文为文档整理,未作本地安装实测。