最近在 MacBook Air M5 上重新安装 OpenClaw 时遇到一个典型问题：

OpenClaw Web UI 可以打开，但是 Gateway 一直无法连接。错误显示gateway重启成功但马上被系统杀死中断，彻底删除openclaw和LanuchAgentm目录下openclaw.Plist所有历史残留文件后按照官方文档重装后均不能解决此问题

表现如下：

访问：

http://127.0.0.1:18789/

显示：

Gateway: 未检测到

connect ECONNREFUSED 127.0.0.1:18789

执行：

openclaw gateway restart

持续失败，错误显示见图二

Gateway restart failed after 13s:
service stayed stopped and port 18789 stayed free.

Service runtime:
status=stopped

Gateway port 18789 status:
free.

初步怀疑：

OpenClaw 卸载重新安装后，macOS LaunchAgent、npm 全局目录、配置目录等文件权限发生变化，导致 launchd 无法正常启动 Gateway 服务。

一键修复命令合集

如果确认希望全部归属当前用户：

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

最后：

openclaw gateway restart

openclaw gateway status --deep

配置完后本地gateway start 状态成功

修复根因分析：

1. 使用openclaw doctor 

反复使用openclaw doctor 以及fix指令，反复删除所有残留文件卸载重装，但是此问题始终在openclaw配置完成后无法启动gateway.后面分析路径以我本人用户(dingxinran)本地路径展示。

2. 检查 OpenClaw 文件权限

OpenClaw 主要涉及以下目录：

目录	作用
~/.openclaw	OpenClaw 配置、Agent、Session、日志
~/.npm-global	npm 全局安装的 OpenClaw 程序
~/Library/LaunchAgents	macOS 用户级服务

首先检查：

ls -ld ~/.openclaw

ls -ld ~/.npm-global

ls -ld ~/Library/LaunchAgents

正常应该类似：

drwx------  dingxinran staff ~/.openclaw

drwxr-xr-x  dingxinran staff ~/.npm-global

drwx------ dingxinran staff ~/Library/LaunchAgents

重点：

所有权应该属于当前登录用户，而不是 root。

---

3. 修复 OpenClaw 配置目录权限

如果发现：

例如：

root staff ~/.openclaw

或者：

root staff ~/Library/Logs/openclaw

说明之前可能使用 sudo 安装或删除导致权限污染。

执行：

sudo chown -R $(whoami):staff ~/.openclaw

检查：

ls -ld ~/.openclaw

应该变成：

dingxinran staff

---

4. 修复 npm 全局安装目录权限

OpenClaw CLI 位于：

which openclaw

例如：

/Users/dingxinran/.npm-global/bin/openclaw

检查：

ls -ld ~/.npm-global

如果不是当前用户：

执行：

sudo chown -R $(whoami):staff ~/.npm-global

再次确认：

ls -ld ~/.npm-global

结果：

drwxr-xr-x dingxinran staff

---

5. 修复 LaunchAgent 权限

OpenClaw Gateway 通过 macOS LaunchAgent 管理：

路径：

~/Library/LaunchAgents/ai.openclaw.gateway.plist

检查：

ls -lh ~/Library/LaunchAgents/

如果发现：

root staff ai.openclaw.gateway.plist

执行：

sudo chown -R $(whoami):staff ~/Library/LaunchAgents

然后确认：

ls -lh ~/Library/LaunchAgents/ai.openclaw.gateway.plist

正确：

-rw------- dingxinran staff ai.openclaw.gateway.plist

---

6. 修复 OpenClaw 日志目录权限

排查过程中发现：

ls -ld ~/Library/Logs/openclaw

结果：

drwxr-xr-x root staff

说明日志目录被 root 创建。

这会导致：

• launchd 无法写 stdout/stderr
• Gateway 启动异常退出
• 日志无法生成

修复：

sudo chown -R $(whoami):staff ~/Library/Logs/openclaw

检查：

ls -ld ~/Library/Logs/openclaw

应该：

dingxinran staff

---

7. 清理 LaunchAgent 重新加载

权限修复后，需要重新加载 macOS 服务。

先卸载：

launchctl bootout gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist

如果提示：

Could not find service

说明当前服务已经不存在，可以继续。

重新加载：

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.gateway.plist

查看：

launchctl print gui/$UID/ai.openclaw.gateway

正常：

state = running
active count = 1

---

8. 重启 Gateway 验证

执行：

openclaw gateway restart

检查：

openclaw gateway status --deep

正常：

Runtime: running

Connectivity probe: ok

Listening:
127.0.0.1:18789

说明：

• LaunchAgent 权限正常
• Node 可执行
• Gateway 服务正常启动

---

9. 权限问题总结

本次怀疑权限问题主要来源：

1）sudo 操作导致文件归属 root

例如：

sudo npm install -g openclaw

或者：

sudo rm -rf ~/.openclaw

可能产生：

root:staff

文件。

---

2）卸载重新安装残留旧 LaunchAgent

删除 npm 包：

npm uninstall -g openclaw

不会自动删除：

~/Library/LaunchAgents/ai.openclaw.gateway.plist

导致：

旧服务仍然存在。

---

3）日志目录权限异常

例如：

~/Library/Logs/openclaw

属于：

root staff

launchd 无法正常写入。

结论

在 OpenClaw macOS 环境中，权限污染是 Gateway 重启失败的重要排查方向。

尤其是在：

• 卸载 OpenClaw
• npm 全局重新安装
• 使用 sudo 操作
• 删除 ~/.openclaw 后重新初始化

这些场景下，应优先检查：

~/.openclaw
~/.npm-global
~/Library/LaunchAgents
~/Library/Logs/openclaw

是否仍属于：

当前用户:staff

而不是：

root:staff

不过在本次案例中，权限修复后 Gateway 最终启动，但仍出现后续 Agent 会话异常，因此还需要继续排查 LaunchAgent 配置、Session 状态、模型认证以及 Agent 数据残留问题。