2. 部署前的环境准备

2.1 系统版本建议

推荐使用 Windows 10 22H2 及以上，或 Windows 11 21H2 及以上。家庭版虽然也能部署，但部分本地策略（gpedit.msc）和容器功能会缺失，优先建议专业版或企业版。

在 PowerShell 中确认版本：

2.2 必装组件

安装 Python 时务必勾选 “Add python.exe to PATH”，否则后续所有命令都要写绝对路径，这是第一颗最常见的雷。

2.3 验证环境

如果 python 提示不是内部或外部命令，说明 PATH 未生效，重新打开终端或手动添加：

3. 路径问题全梳理

3.1 反斜杠与转义

Windows 路径以 \ 分隔，但在 Python 字符串中 \ 是转义字符。配置文件中常见错误：

3.2 路径中包含空格

很多用户把项目放在 C:\Program Files\OpenClaw 或 C:\Users\Zhang San\OpenClaw，路径里的空格会导致 Shell 命令解析错误。

不建议将运行目录放在 Program Files，因为该目录受系统保护且带空格。建议部署目录：

如果路径必须包含空格，引用时务必加引号：

3.3 中文用户名与系统编码

Windows 用户名是中文时，%USERPROFILE% 会包含中文字符，可能导致 Python 读取文件时编码错误或第三方库无法识别。

临时解决方案：

永久方案是在系统环境变量中设置：

注意：追加环境变量时如果原变量已存在，上面的 SetEnvironmentVariable 会覆盖整个变量。若只想追加 Path，应先读取旧值再拼接。

3.4 相对路径与工作目录

OpenClaw 启动时常把工作目录当作基准路径读取配置、日志和静态资源。如果你在 C:\ 或桌面用绝对路径启动 python C:\OpenClaw\app.py，程序内部使用相对路径时就会找不到文件。

正确启动姿势：必须先切换到项目目录

如需后台运行，使用 Start-Process 并指定工作目录：

3.5 日志与数据目录权限

OpenClaw 默认可能在安装目录下写日志或缓存。当安装目录位于 Program Files 或 C:\ 根目录时，普通用户通常没有写权限。建议在配置文件里显式指定可写目录：

并预先创建：

4. 权限问题全梳理

4.1 UAC 与“以管理员身份运行”

OpenClaw 若需要监听 80、443 等小于 1024 的端口，或写入 Program Files、注册服务，通常需要管理员权限。但“贪方便一直用管理员”也会带来隐患：管理员启动后创建的文件、日志、配置可能归管理员账户所有，普通用户后续无法改动。

建议策略：

• 开发调试：用普通用户运行，端口选择 8000、8080 等高位端口；
• 生产部署：用管理员权限注册为 Windows 服务，让服务在系统账户下运行；
• 不要全程用管理员跑开发环境。

以管理员身份启动 PowerShell：

4.2 PowerShell 执行策略拦截脚本

运行 OpenClaw 的安装脚本或启动脚本时，如果遇到：

说明当前执行策略为 Restricted。查看策略：

为当前用户放开脚本执行：

恢复原策略：

4.3 目录 ACL 权限不足

如果普通用户无法写入或读取某些目录，可以手动授予当前用户完全控制权限：

(OI)(CI) 表示对象继承和容器继承，F 为完全控制，/T 递归应用到子目录和文件。注意 Windows 路径带空格时记得用双引号包裹。

4.4 注册为 Windows 服务

生产环境建议把 OpenClaw 注册成 Windows 服务，实现开机自启和崩溃自动重启。以 Python 项目为例，可借助 NSSM：

服务账户默认是 LocalSystem，权限很高；如果 OpenClaw 需要访问网络共享或特定凭据，应在服务属性里配置专用账户，并确保该账户对项目目录有读写权限。

4.5 防火墙出站/入站规则

OpenClaw 既需要监听本地端口（入站），也可能需要调用外部 API（出站）。默认情况下 Windows 防火墙对出站通常放行，但一些企业策略会严格限制。

放行入站端口（以 8080 为例）：

检查端口监听状态：

如果 0.0.0.0:8080 表示监听所有网卡，127.0.0.1:8080 表示仅本机可访问，需要检查配置是否把 host 写成了 localhost 或 127.0.0.1。

5. 拦截问题全梳理

5.1 Defender 实时保护“吞文件”

下载 OpenClaw 安装包或运行释放器时，Windows Defender 可能因启发式扫描或误报直接隔离文件。

排障步骤：

处理建议：

1. 优先从官方仓库或可信发布页下载，核对哈希；
2. 若确认为误报，在“病毒和威胁防护 → 保护历史”中恢复；
3. 为开发目录添加排除项（仅在你信任该目录时）：

恢复后可关闭实时保护再重试，但部署完成后建议重新开启：

5.2 SmartScreen 拦截安装程序

双击安装包时若出现“Windows 已保护你的电脑”，说明 SmartScreen 提示未知发布者。点击“更多信息 → 仍要运行”即可。

5.3 杀毒软件静默阻断

360、火绒、腾讯管家等第三方安全软件可能拦截 OpenClaw 的进程、端口监听或 DLL 注入。常见表现：

• 进程启动后立刻退出，无任何报错；
• 端口监听成功但外部无法访问；
• 日志中频繁出现 Permission denied、Access is denied。

排查方法：

1. 暂时退出安全软件测试是否能正常运行；
2. 将 OpenClaw 安装目录、数据目录加入白名单；
3. 检查安全软件的“网络防护”“端口保护”选项。

5.4 系统代理与拦截

如果公司网络或本机开启了 HTTP 代理，OpenClaw 调用外部 API 时可能被代理拦截或返回 407 认证错误。可在项目配置中显式设置代理：

直连请求需要绕过代理时设置：

5.5 hosts 与 DNS 解析问题

OpenClaw 需要连接远程 API 时，如果 DNS 被污染或 hosts 配置错误，会出现超时或 getaddrinfo failed。可在 C:\Windows\System32\drivers\etc\hosts 中手动指定 IP 与域名映射，修改后需要管理员权限保存，并刷新 DNS：

6. 完整部署流程（避坑版）

6.1 创建工作目录

6.2 拉取并安装项目

如果 Activate.ps1 被执行策略拦截，参考 4.2 节放开当前用户脚本权限。

6.3 配置关键项

编辑 config.yaml，重点确认路径与监听地址：

6.4 放行防火墙

6.5 启动与验证

另开终端验证：

6.6 注册服务（生产环境）

7. 常见故障排查表

8. 总结

Windows 部署 OpenClaw 的坑看似杂乱，其实可以归纳为一条主线：先解决“路径对不对”，再解决“权限够不够”，最后排查“有没有被拦截”。

• 路径：统一使用无空格、无中文的短路径，优先用正斜杠或原始字符串；
• 权限：普通用户跑开发、服务账户跑生产，端口与目录权限分开管理；
• 拦截：从 Defender、防火墙、SmartScreen 到第三方杀软逐层放行，必要时设置代理与白名单。

把这三个维度排查清楚，绝大多数启动失败、端口不通、文件丢失的问题都能迎刃而解。建议把这套检查顺序固化成你的排障清单，下次遇到 Windows 部署问题直接从路径开始排查，会比盲目搜报错高效得多。