【Bug已解决】OpenClaw 报错 gateway.auth.mode 未配置导致 Unauthorized 解决方案

1. 问题描述

OpenClaw Gateway 已经能够正常启动，但调用其接口时始终返回未授权错误：

HTTP 401 Unauthorized
{"error": "Missing or invalid authentication token"}

检查后发现，是因为网关的认证模式配置项缺失。

1.1 具体现象

1. Gateway 进程本身运行正常，status 命令显示 running
2. 所有对网关接口的调用都被拒绝，返回未授权
3. 检查配置文件，发现完全没有配置认证相关的字段
4. 从官方文档示例复制的配置，可能省略了这部分内容（示例配置有时为了简洁会忽略生产环境必需的安全配置）

这个问题的本质是网关的认证机制配置项（gateway.auth.mode）缺失，而认证 Token（OPENCLAW_GATEWAY_TOKEN）也没有正确设置或导出，导致所有请求都因为无法通过认证校验而被拒绝。

2. 原因分析

OpenClaw Gateway 作为对外提供服务的接口层，出于安全考虑，默认要求所有调用都携带有效的认证凭据。这个认证机制需要通过配置显式声明认证模式，并配套设置对应的认证令牌，两者缺一不可：

Gateway 启动，加载配置
        ↓
检查 gateway.auth.mode 配置项
        ↓
   认证模式是否已明确配置？
      ├─ 已配置 → 按配置的模式校验请求中的认证凭据
      └─ 未配置/配置不完整 → 所有请求均无法通过认证校验
                                  ↓
                            401 Unauthorized

3. 解决方案

方案一：显式配置认证模式和对应的 Token（官方文档给出的标准修复方式）

设置 gateway.auth.mode 和 gateway.auth.token
（或者通过环境变量导出 OPENCLAW_GATEWAY_TOKEN）
并重启服务

具体配置示例：

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-secure-random-token-here"
    }
  }
}

或者通过环境变量方式配置：

export OPENCLAW_GATEWAY_TOKEN="your-secure-random-token-here"
openclaw gateway restart

方案二：确认调用方在请求中正确携带了对应的认证凭据

配置好服务端的认证要求后，还需要确保所有调用方（客户端脚本、其他系统集成）在请求头中携带对应的 Token：

curl -H "Authorization: Bearer your-secure-random-token-here" \
     https://your-gateway-host/api/endpoint

方案三：生成一个足够随机、安全的 Token，而非使用简单的默认值

# 生成一个随机安全的 Token
openssl rand -hex 32

避免使用类似"123456"这种容易被猜测的弱 Token，尤其是在网关暴露给公网访问的场景下。

方案四：运行诊断命令确认认证配置的完整性

openclaw doctor

诊断命令通常能检测出认证配置缺失这类常见的安全隐患，并给出明确的提示。

方案五：如果网关仅用于本地开发调试，评估是否可以临时使用宽松的认证模式

对于纯本地开发环境（网关只监听本地地址，不对外暴露），可以评估当前版本是否支持配置一个相对宽松的认证模式作为开发调试的便利选项，但生产环境和任何对外暴露的部署场景，都必须配置严格的认证机制，不能因为图方便而完全禁用认证。

4. 各方案对比总结

方案	适用场景	推荐指数
显式配置认证模式和 Token	根本解决方式，必须执行	⭐⭐⭐⭐⭐
确认调用方携带凭据	服务端配置正确后的下一步验证	⭐⭐⭐⭐⭐
生成安全随机 Token	安全最佳实践	⭐⭐⭐⭐⭐
诊断命令确认配置完整性	快速检查是否有遗漏	⭐⭐⭐⭐
本地开发的宽松模式	仅限纯本地不对外暴露的场景	⭐⭐

5. 常见问题 FAQ

5.1 网关只在本地使用，是不是就不需要配置认证了？

即使是本地使用，配置基础的认证机制仍然是更安全稳妥的做法，尤其是当同一台机器上可能运行多个其他服务或存在多用户访问的情况下。如果确实是完全隔离的单用户本地开发环境，可以评估风险后临时简化，但不建议将这种简化配置带入任何生产或共享环境。

5.2 Token 泄露后应该如何处理？

一旦怀疑 Token 泄露，应该立即生成一个新的随机 Token 并更新配置，同时重启网关服务使新 Token 生效，并同步更新所有合法调用方使用的凭据，尽快让泄露的旧 Token 失效。

5.3 除了 Token 认证模式，是否还有其他认证方式可选？

具体支持的认证模式以当前版本官方文档说明为准，除了简单的 Token 认证，部分版本可能还支持更复杂的认证机制（如签名校验、OAuth 等），如果有更高的安全需求，建议查阅官方文档评估更适合的认证方案。

5.4 排查清单速查表

□ 1. 确认 gateway.auth.mode 是否已在配置中明确设置
□ 2. 确认对应的认证 Token 是否已正确配置或导出
□ 3. 确认调用方请求中是否正确携带了认证凭据
□ 4. 生成足够随机安全的 Token，避免使用弱密钥
□ 5. 运行 openclaw doctor 检查认证配置的完整性
□ 6. 生产环境务必配置严格的认证机制，不能简化省略

6. 总结

OpenClaw Gateway 返回 401 Unauthorized 的本质是认证模式配置缺失，导致所有请求都无法通过必要的身份校验，这是网关安全机制在正常发挥保护作用。核心处理思路：

1. 显式配置 gateway.auth.mode 和对应的认证 Token，这是解决问题的根本方式；
2. 确保所有合法调用方在请求中正确携带认证凭据，服务端和客户端配置需要匹配；
3. 使用足够随机安全的 Token，并在生产环境严格执行认证机制，不能因为图方便而简化。

最佳实践建议：把"认证配置是否完整"作为部署 OpenClaw Gateway 的标准检查清单项之一，尤其是在网关对外暴露的场景下，务必在正式启用前完成安全配置的自查，而不是等到真正遇到未授权报错才想起补充。