装OpenClaw这件事，说难不难，但真要踩到坑里也挺耽误时间的。今天把我踩过的几个坑整理出来，给大家省点排查时间。
下载地址：https://top.wokk.cn，有详细版本说明可以先看一下。
坑1：PowerShell执行策略拦路
这个应该是Windows用户遇到最多的一个问题。
症状：运行安装脚本时报错，提示"无法加载文件，因为在此系统上禁止运行脚本"。
原因：Windows默认的脚本执行策略是Restricted，所有本地脚本都不让跑。
解决：
`powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
`
输入Y确认，然后再跑安装脚本就好了。这里有个容易搞错的地方：-Scope参数要用CurrentUser，别用LocalMachine。用LocalMachine的话需要管理员权限，公司电脑大概率没这个权限。
坑2：Node.js版本不对
这个坑比较隐蔽，不报错但装完之后启动有问题。
症状：安装过程一切正常，但启动网关的时候报各种奇怪的错误，比如模块找不到、异步操作失败之类的。
原因：OpenClaw要求Node.js 22.x以上，低版本虽然能装上但跑不起来。
解决：
`powershell
node -v
`
先查一下当前版本。如果低于v22，去官网下个新的LTS版本装上。
建议用nvm-windows管理Node版本，这样切换起来方便。以后想测试不同版本的OpenClaw也不需要反复重装Node。
坑3：路径里有中文或者空格
这个坑专门针对Windows用户，macOS一般不会遇到。
症状：文件操作相关的功能全部失效，日志里显示"路径解析失败"。
原因：OpenClaw内部调用Node.js的path模块时，对中文和空格处理有问题。
解决：
确保安装目录和配置目录的路径都是纯英文，没有空格，也没有中文。最好把OpenClaw装在C:\openclaw或者C:\tools\openclaw这种简单路径下。
如果在初始化的时候已经用了带中文的路径，只能重装。配置文件也要清掉重新配置。
坑4：端口被占用
症状：网关启动失败，日志里写着"Port 18789 is already in use"。
解决分两步：
第一步，看是谁占用了端口：
`powershell
netstat -ano | findstr 18789
`
这会显示占用端口的进程ID。
第二步，决定怎么办：
- 如果是你之前开的OpenClaw，关掉那个进程或者重启电脑
- 如果是其他程序占用，改OpenClaw的端口
改端口的方法：
`yaml
gateway:
port: 3000 # 改成其他端口
`
坑5：初始化的时候网络超时
这个在初始化向导阶段特别容易遇到。
症状：向导停在"正在连接AI模型服务商"这一步，等很久之后报超时错误。
原因：国内网络访问国外API不稳定。
解决：
换国内模型服务商，比如Kimi或者GLM。这两家在国内都有节点，速度和稳定性都比国外的好很多。
如果坚持要用OpenAI或者Claude，可以配置代理：
`yaml
proxy:
enabled: true
url: http://127.0.0.1:7890 # 你的代理地址
`
坑6：API Key填错了
初始化向导填API Key的时候，最容易犯两个错误：
1. 填了错误的Key格式
不同服务商的Key格式不一样：
- OpenAI：sk-开头
- Kimi：sk-开头
- GLM：不用sk-前缀
填之前先在对应平台确认一下Key的格式。
2. Key权限不足
有些平台创建Key的时候可以选择权限范围。如果创建的时候只选了"对话"，那这个Key就不能用来做其他操作。遇到这种情况只能去平台重新创建一个权限更全的Key。
坑7：Mac上的Rosetta2问题
Apple Silicon芯片的Mac专用坑。
症状：安装成功，但运行时报错"Bad CPU instruction type"。
原因：安装的是x86版本的OpenClaw，但Mac运行的是ARM原生模式。
解决：
装Rosetta2：
`ash
softwareupdate --install-rosetta
`
装完之后重新安装OpenClaw就可以了。
总结一下
装OpenClaw的坑主要就这几类：权限问题、版本问题、路径问题、网络问题、配置问题。按顺序排查的话，一般半小时内能解决。
遇到问题别急着重装，先看看日志在哪一步卡住了。日志路径是~/.openclaw/logs/，里面记录了详细的执行过程，对排查问题很有帮助。
如果上面这些都没覆盖到你的情况，评论区说一下具体现象，大家一起看看。关于OpenClaw的更多常见问题，https://top.wokk.cn上也在持续更新。
