OpenClaw网关连接失败需按服务状态、权限归属、绑定地址三方面排查：先用openclaw gateway status确认运行状态，强制清理残留进程；macOS用户修复~/.openclaw等目录权限并重载LaunchAgent；将config.yaml中bind_address改为0.0.0.0，检查端口占用；重置或注入有效gateway-token；最后验证status为active(running)并查日志。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw部署完成后，浏览器访问 http://127.0.0.1:18789 显示连接被拒绝、控制台空白或提示“Gateway: 未检测到”，说明网关进程未真正监听端口，或认证链路中断，不是网络设置问题也不是浏览器缓存导致——必须从服务状态、权限归属、绑定地址三方面逐层验证。
确认网关真实运行状态并清理残留进程
别信 UI 上的“正在启动”提示，先用命令确认进程是否存活：执行 openclaw gateway status。若返回 offline 或报错 command not found，说明服务根本没跑起来，或者命令路径损坏。
立即执行强制停服：openclaw gateway stop。如果命令无响应，证明进程已僵死，必须手动清空：
macOS/Linux 下运行：ps aux | grep openclaw-gateway | awk '{print $2}' | xargs kill -9；Windows 用户打开任务管理器 → 搜索 “openclaw-gateway” → 全部结束任务。
【不清理残留进程直接重启，90%概率复现离线】
修复 macOS 用户级服务权限与 LaunchAgent 加载异常
MacBook Air M5 等 Apple Silicon 设备重装 OpenClaw 后，常见问题是 ~/.openclaw、~/.npm-global、~/Library/LaunchAgents 三个目录归属用户错误，导致 launchd 拒绝加载 gateway.plist。
执行以下四条归属修复命令（复制粘贴即可）：
sudo chown -R $(whoami):staff ~/.openclaw
sudo chown -R $(whoami):staff ~/.npm-global
sudo chown -R $(whoami):staff ~/Library/LaunchAgents
sudo chown -R $(whoami):staff ~/Library/Logs/openclaw
然后卸载并重新注入服务配置：
launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist
校验并修正网关监听地址与端口配置
即使服务启动成功，若绑定地址仍是 127.0.0.1，本机浏览器也无法访问——这是 macOS 和 Linux 上最隐蔽的失败原因。
第一步：打开配置文件 ~/.openclaw/config.yaml（注意是 YAML 格式，不是 JSON）
第二步：查找 gateway: 区块，确认存在且缩进正确的字段：bind_address: 0.0.0.0。如果该行缺失或写成 127.0.0.1，请手动修改为 0.0.0.0。
第三步：检查端口是否被占用。执行 lsof -i :18789，若有输出，记下 PID 并执行 kill -9 [PID]；若不想杀进程，可临时换端口：在 config.yaml 中添加 port: 18888（注意缩进对齐），保存后访问 http://127.0.0.1:18888。
重置认证凭据并注入有效网关令牌
方法一：删除旧令牌文件
执行 rm -f ~/.openclaw/.gateway-token，这会强制网关下次启动时生成新 token。
方法二：手动注入远程 token（仅适用于使用云端模型）
执行 openclaw config set gateway.remote.token "your_actual_token_here"，【此处必须填入有效且未过期的 token，无效 token 会导致服务启动后秒退】。
方法三：跳过配置校验强制重装
执行 openclaw gateway install --force，此操作覆盖损坏的二进制和模板配置，但保留用户技能数据。
验证服务是否真正运行
① 启动服务：openclaw gateway start。
② 立即验证：openclaw gateway status，输出必须含 active (running) 且无 error 字样。
③ 若仍失败，直取日志定位：tail -n 50 ~/.openclaw/logs/gateway.log，重点搜 ERR、token、bind 关键词。
