OpenClaw gateway token missing 怎么解决？

在部署或使用 OpenClaw 时，很多人会遇到 gateway token missing 这个错误。它看起来像是程序崩了，其实多数情况下是网关认证配置没有填对，或者 Control UI 与后端服务之间的 token 不一致。

这篇文章会用中文把 OpenClaw gateway token missing 怎么解决 讲清楚，适合正在折腾本地 AI 部署、OpenClaw 网关、Control UI 和 API 代理服务的用户参考。

为什么出现这个错误

gateway token missing 的直接意思是：请求进入 gateway 时，没有带上服务要求的 token。

常见原因包括：

没有在环境变量里配置 gateway token
Control UI 里没有填写 token
前端填写的 token 和后端设置的 token 不一致
修改配置后没有重启服务
使用了旧缓存、旧容器或旧配置文件
反向代理转发时丢失了认证请求头

如果你刚刚完成 OpenClaw 部署，第一次打开页面就看到这个错误，优先检查 token 配置，而不是急着重装整个项目。

gateway token 是什么

gateway token 可以理解为 OpenClaw 网关服务的访问口令。

在本地 AI 部署里，gateway 通常负责接收请求、转发请求、管理模型接口或连接后端服务。为了避免任何人都能直接调用你的网关，系统会要求请求携带一个 token。

这个 token 不是模型 API key，也不一定是 OpenAI、Claude 或其他模型厂商的 key。它更像是你自己部署的 OpenClaw 网关与 Control UI 之间的内部访问凭证。

简单说：

模型 API key 用来访问模型服务
gateway token 用来访问你的 OpenClaw 网关
Control UI 需要知道 gateway token，才能正常连接 gateway

如何修复

修复思路是让后端 gateway 和前端 Control UI 使用同一个 token。

你可以按下面步骤排查：

找到 OpenClaw 的环境变量配置文件，常见文件名可能是 .env、.env.local 或部署平台里的 Environment Variables。
检查是否存在类似 GATEWAY_TOKEN、OPENCLAW_GATEWAY_TOKEN 或项目文档指定的 token 配置项。
如果没有，就新增一个足够随机的 token，例如一串只有你自己知道的长字符串。
打开 Control UI，找到 gateway、API、认证或 token 相关设置。
把 Control UI 里的 token 设置成和后端环境变量完全一致。
保存配置后，重启 gateway 服务和 Control UI。
重新打开页面测试。

如果你使用 Docker 部署，还需要确认容器已经重新加载环境变量。只修改 .env 文件但不重启容器，错误通常不会消失。

Control UI 设置方法

在 Control UI 中，重点检查 gateway 地址和 token 两项。

gateway 地址一般是你的后端服务地址，例如本地部署时可能是：

http://localhost:xxxx

token 则填写你在后端环境变量中配置的同一串内容。注意不要多复制空格、换行或引号。

推荐做法：

先在后端配置一个明确的 gateway token
再复制同一串 token 到 Control UI
保存后刷新页面
如果仍然报错，重启服务并清理浏览器缓存

如果 Control UI 有多个配置环境，例如 local、dev、production，要确认你改的是当前正在使用的环境。

常见问题

token 明明填了，为什么还报错？

最常见原因是前后端 token 不一致。请逐字检查大小写、空格、引号和换行。

修改 `.env` 后为什么不生效？

很多服务启动时只读取一次环境变量。修改 .env 后需要重启 Node 服务、Docker 容器或部署实例。

gateway token 和 API key 是同一个吗？

通常不是。gateway token 是访问你自己网关的认证口令，API key 是访问模型供应商或模型服务的凭证。

反向代理会导致这个问题吗？

会。如果你使用 Nginx、Cloudflare、Vercel rewrites 或其他代理，要确认认证请求头没有被过滤或覆盖。

可以关闭 token 验证吗？

不建议。即使是本地部署，也最好保留 token 验证。特别是当服务暴露到公网时，关闭验证会带来明显安全风险。

总结

OpenClaw gateway token missing 通常不是复杂故障，而是网关 token 没有配置、没有传递或前后端不一致。

排查时记住一个核心原则：后端 gateway 配置的 token，要和 Control UI 里填写的 token 完全一致。修改后重启服务，再检查代理和缓存问题，通常就能解决。

如果你正在做本地 AI 部署，建议把 gateway token、模型 API key、Control UI 地址和部署环境分开记录。这样以后遇到类似认证错误时，可以更快定位问题。