问题背景
libuv 双栈 IPv6 问题
OpenClaw 网关基于 Node.js（底层用 libuv）：
- libuv 默认尝试双栈 IPv6绑定（::1）
- Windows 上 ::1 行为与 Linux/macOS 不同
- 可能导致 localhost HTTP 请求卡死
表现
Windows 用户可能遇到：
- OpenClaw 启动后 HTTP 接口偶发不响应
- 浏览器访问 localhost:18789 转圈
- 重启网关后正常一段时间又出问题
- 日志看不到错误
v2026.5.4 修复
v2026.5.4 在 Windows 上：
# 默认配置（自动应用）
gateway:
bind: "127.0.0.1" # 仅 IPv4
避免 IPv6 双栈问题，localhost 永远稳定。
升级路径
升级到 v2026.5.4+
npm install -g openclaw@latest
openclaw doctor
升级后 Windows 自动应用 IPv4 绑定。
验证
# 查看监听
netstat -an | findstr :18789
# 应该看到：
# TCP 127.0.0.1:18789 0.0.0.0:0 LISTENING
# 而不是 [::1]:18789
自定义网关配置
仅本机访问
gateway:
bind: "127.0.0.1"
port: 18789
仅本机程序可访问。
允许局域网访问
gateway:
bind: "0.0.0.0"
port: 18789
security:
allowedIps:
- "192.168.1.0/24"
- "127.0.0.1"
Windows 防火墙配置
允许 OpenClaw
# 允许入站（仅本机）
New-NetFirewallRule -DisplayName "OpenClaw Gateway" `
-Direction Inbound `
-Protocol TCP `
-LocalPort 18789 `
-Action Allow `
-Profile Private
阻止公网访问
# 阻止公网
New-NetFirewallRule -DisplayName "OpenClaw Block Public" `
-Direction Inbound `
-Protocol TCP `
-LocalPort 18789 `
-Action Block `
-Profile Public
服务化部署
安装为 Windows 服务
# config.yaml
service:
enabled: true
name: "OpenClaw"
description: "OpenClaw AI Gateway"
startMode: "auto" # 开机启动
recovery:
onFailure: "restart"
delay: "10s"
注册服务
# 以管理员运行
openclaw service install
# 启动
openclaw service start
# 状态
openclaw service status
卸载
openclaw service stop
openclaw service uninstall
任务计划程序
替代方案：使用 Task Scheduler
# 创建任务
schtasks /Create /TN "OpenClaw" `
/TR "C:\path\to\openclaw.exe gateway" `
/SC ONLOGON `
/RL HIGHEST
适合：
- 不想用服务方式
- 用户登录后启动
- 简单部署场景
常见 Windows 问题
问题 1：端口被占用
# 查看占用 18789 端口的进程
netstat -ano | findstr :18789
# 输出示例：
# TCP 127.0.0.1:18789 0.0.0.0:0 LISTENING 12345
# 终止进程（PID = 12345）
taskkill /PID 12345 /F
或修改 OpenClaw 端口：
gateway:
port: 18790
问题 2：杀毒软件阻止
某些杀毒软件可能误报：
- 添加 OpenClaw 到白名单
- 排除
~\.openclaw\目录 - 排除
node.exe和npm.exe
问题 3：路径过长
Windows 路径有 260 字符限制：
# 启用长路径支持（需要管理员）
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" `
-Value 1 `
-PropertyType DWORD `
-Force
或使用短路径：
# config.yaml
storage:
basePath: "C:\\openclaw"
问题 4：权限问题
# 给 OpenClaw 目录足够权限
icacls "%APPDATA%\openclaw" /grant "%USERNAME%:F" /T
WSL2 vs 原生 Windows
原生 Windows
优势：
- 简单直接
- 无虚拟化开销
- 集成系统通知
劣势：
- 部分工具兼容性
- 路径分隔符差异
WSL2
优势：
- Linux 工具生态
- 更好的 Docker 支持
- 接近原生 Linux
劣势：
- 资源占用
- 文件系统跨界性能
- 网络配置复杂
选择建议
- AI 开发：WSL2（更好的 GPU、CUDA 支持）
- 简单使用：原生 Windows
- 企业部署：Windows Server（原生）
Windows 性能优化
启用硬件加速
performance:
hardware:
gpu: "auto" # auto | nvidia | amd | intel | none
nvidiaCuda: "12.x"
优化 Node.js 参数
runtime:
node:
maxOldSpaceSize: 4096 # 4GB 堆内存
maxSemiSpaceSize: 64
使用 SSD
OpenClaw 大量使用磁盘 IO（记忆系统、日志）：
- 安装目录在 SSD
- 配置目录在 SSD
- 日志目录可在 HDD（轮转后）
storage:
basePath: "D:\\openclaw" # SSD
logsPath: "E:\\openclaw-logs" # HDD（可选）
Windows Defender 排除
全局排除
# 排除文件夹
Add-MpPreference -ExclusionPath "$env:APPDATA\openclaw"
# 排除进程
Add-MpPreference -ExclusionProcess "node.exe"
Add-MpPreference -ExclusionProcess "openclaw.exe"
验证
Get-MpPreference | Select-Object ExclusionPath, ExclusionProcess
网络代理
公司代理
network:
proxy:
http: "http://proxy.company.com:8080"
https: "http://proxy.company.com:8080"
noProxy: "localhost,127.0.0.1,*.internal"
NPM 代理
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
监控和日志
Windows Event Viewer
OpenClaw 关键事件：
- 启动/停止
- 错误和警告
- 安全事件
logging:
windowsEvents:
enabled: true
source: "OpenClaw"
日志位置
%APPDATA%\openclaw\logs\
├── gateway.log # 网关日志
├── agents.log # Agent 日志
├── errors.log # 错误日志
└── access.log # 访问日志
故障排查清单
# 1. 验证版本
openclaw --version
# 2. 整体诊断
openclaw doctor
# 3. 网关状态
openclaw gateway status
# 4. 端口检查
netstat -an | findstr :18789
# 5. 查看日志
type "%APPDATA%\openclaw\logs\gateway.log" | Select-Object -Last 50
# 6. 测试连接
curl http://127.0.0.1:18789/health
注意事项
- Windows IPv4 绑定修复需要 OpenClaw v2026.5.4 或更高版本
- 仍可能有特殊场景需要 IPv6（手动配置）
- 服务化部署建议使用专用账户运行
- 杀毒软件白名单是常见问题源
- 路径使用反斜杠
\\或正斜杠/（OpenClaw 都支持） - 国内用户配置 NPM 镜像加速安装
- WSL2 用户参考 Linux 教程
- 企业部署建议用 Windows Server 而非 Windows 10/11
- 关闭杀毒软件实时监控部分目录而非全局