Gateway 启动 / 运行问题

本页收录近期 GitHub Issues 中 Gateway 相关高频问题，精选有明确解决方案的案例。

问题 1：配置 auth token 后 CLI 报 `token_mismatch`

来源：GitHub #38617（2026-03）

现象：在 openclaw.json 中配置了 gateway.auth.token 后，CLI 执行 openclaw login 时报认证错误 token_mismatch，无法连接 Gateway。

原因：CLI 本地存储的旧 token（位于 ~/.openclaw/credentials.json）与 Gateway 配置的新 token 格式不匹配。CLI 使用缓存的凭证而非配置文件中的值。

解决方法：

bash

# 删除本地缓存的凭证
rm ~/.openclaw/credentials.json

# 重新登录
openclaw login

提示：每次修改 gateway.auth.token 后都需要执行此操作，否则 CLI 会持续使用旧 token。

来源：GitHub #38628（2026-03）

现象：笔记本电脑或移动设备切换 WiFi / 有线网络后，Gateway 进程崩溃，报 AssertionError，日志显示 IPv4 地址变为 undefined。

原因：网络切换瞬间，系统 IPv4 地址短暂变为 undefined，Gateway 的断言检查未处理此中间状态，直接抛出错误。

解决方法：

立即恢复：重启 Gateway

bash

openclaw gateway restart

长期方案：在配置中绑定到 0.0.0.0 而非具体 IP，避免网络切换时绑定地址失效：

json

{
  "gateway": {
    "host": "0.0.0.0"
  }
}

来源：GitHub #38682（2026-03）

现象：macOS 上使用 VPN 时，VPN 断线重连后 Gateway 不会自动恢复，需要手动重启。

原因：macOS LaunchAgent 无法检测到 Gateway 进程的网络状态变化，也不会在网络恢复后触发重启。

解决方法：

方案 1：在 LaunchAgent plist 中添加网络状态监测：

xml

<!-- ~/Library/LaunchAgents/ai.openclaw.gateway.plist -->
<key>KeepAlive</key>
<dict>
  <key>NetworkState</key>
  <true/>
</dict>

修改后重新加载：

bash

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

方案 2：使用 openclaw restart 命令绑定到 VPN 客户端的重连事件（需参考具体 VPN 客户端文档）。

来源：GitHub #38721（2026-03）

现象：运行 openclaw stop 后等待很长时间仍超时，Gateway 进程不退出。重新运行 openclaw start 时报 "already running"。

原因：有活跃的子进程句柄（如未完成的 Agent Loop、正在进行中的工具调用）阻止 Gateway 正常关闭。官方正在追踪此问题。

解决方法：

bash

# 强制终止（按 PID，避免误杀其他进程）
openclaw gateway status   # 获取 PID
kill -9 <PID>

# 或使用名称匹配（确认路径属于 openclaw）
pkill -f "openclaw"

注意：使用 pkill -f openclaw 前请确认只有 openclaw 进程匹配，避免误伤其他程序。此问题已在 GitHub 追踪，待官方修复。