OpenClaw macOS中文路径报错：纯英文目录设置规范

核心结论：OpenClaw在macOS上遇到中文路径就会卡死、报错或找不到配置文件，这并非软件缺陷。根源在于其底层依赖的Node.js模块——例如fs、path.resolve——以及整个CLI工具链对非ASCII路径的解析存在硬性限制。尤其是调用sharp、glob、electron-builder这类原生扩展时，会直接抛出ENOTDIR或EACCES异常，毫无回旋余地。

如何确认自己是否也踩了这个坑？操作很直接：

打开终端，执行一条调试命令：openclaw onboard --debug。

如果输出中出现类似 ENOENT: no such file or directory, open '/Users/张三/Documents/openclaw/config.json' 的错误，路径里包含中文用户名或文件夹名，那么问题就在这里。

这一步必须完成。因为从OpenClaw v2026.3.31开始，虽然默认启用了路径预检机制，但它只会提示一句“invalid path”，并不会告知具体哪个字符有问题，极易被误判为权限故障。

强制切换至纯英文系统路径方案

既然根因在于路径，解决方案就直截了当：将整个项目强制迁移到纯英文路径下。

第一步，新建一个不含空格与中文的顶层目录。例如：/Users/ocwork。注意，不能使用/Users/张三/Desktop/OpenClaw，也不能带有空格——/Users/oc work同样不可行。

第二步，将OpenClaw安装包解压或通过git clone到该目录。命令示例：git clone https://github.com/openclaw/core.git /Users/ocwork/openclaw。

第三步，进入该目录后，必须首先锁定环境变量：export OPENCLAW_HOME=/Users/ocwork/openclaw && cd /Users/ocwork/openclaw。这一步不可省略，否则后续所有命令仍会回退到系统默认路径——比如 ~/Library/Application Support——而该路径在中文用户名下天然含有中文字符。

第四步，执行初始化流程：npm run setup → npm run onboard。此时所有日志、缓存、配置文件都会生成在/Users/ocwork/openclaw及其子目录下，全程避开中文字符。

永久禁用系统级中文路径污染

临时解决一次不够，必须根治。以下两种方法，任选其一即可。

方法一：修改Shell启动配置（推荐zsh用户）

编辑~/.zshrc，在末尾添加一行：export HOME="/Users/ocwork"。

需要特别强调：这并非修改你真实的系统家目录，只是让OpenClaw相关进程读取HOME变量时，返回一个纯英文路径。保存后执行source ~/.zshrc，再新开一个终端，验证echo $HOME是否输出/Users/ocwork。

方法二：为OpenClaw单独封装启动脚本

如果你不想改动全局的HOME变量，更精细的做法是编写一个启动脚本。

新建文件 /Users/ocwork/start-claw.sh，内容如下：

#!/bin/zsh
export HOME="/Users/ocwork"
export OPENCLAW_HOME="/Users/ocwork/openclaw"
cd /Users/ocwork/openclaw
npm start

然后赋予执行权限：chmod +x /Users/ocwork/start-claw.sh。

以后只需双击这个脚本，或在终端里输入 /Users/ocwork/start-claw.sh，即可安全启动，不会触发中文路径问题。

最后提醒一句：不要将OPENCLAW_HOME设为/Users/ocwork本身——那样会导致配置文件写入根目录，破坏结构隔离。v2026.3.31版本已明确拒绝这种设定。