OpenClaw Windows 部署与运维

概述

OpenClaw 是多通道 AI 网关。Windows 下通过 npm 安装，入口脚本有 .cmd（CMD）、.ps1（PowerShell）、无扩展名（bash）三种。

当前版本：2026.6.11，安装路径：D:\openclaw，状态目录：~/.openclaw/。

启动方式

关键：用户想要正常聊天必须用 openclaw chat，直接 openclaw 进的是维护模式！

安装后常见问题

1. PowerShell 中 openclaw 报"无法识别此脚本"

根因是 PowerShell 按 ps1 → cmd → 无扩展名 顺序查找可执行文件。如果目录里同时存在 openclaw（bash脚本）和 openclaw.ps1，PowerShell 会优先匹配它们而非 .cmd。

修复步骤：

# 删除 bash 脚本（Windows 不需要）
rm /d/openclaw/openclaw
# 删除 ps1（避免执行策略拦截）
rm /d/openclaw/openclaw.ps1
# 确保 D:\openclaw 在 PATH 最前面

2. 旧 npm 全局版本冲突

如果之前通过 npm install -g openclaw 安装过，C:\Users\<user>\AppData\Roaming\npm\ 下有残留。

# 卸载旧版
npm uninstall -g openclaw
# 手动清理残留
rm -f "$HOME/AppData/Roaming/npm/openclaw"*
rm -rf "$HOME/AppData/Roaming/npm/node_modules/.openclaw-*"

3. Gateway 服务指向旧路径

如果 OpenClaw 从 C 盘迁移到 D 盘，Gateway 的 Windows 计划任务仍指向旧路径。

cd /d/openclaw && ./openclaw.cmd gateway install --force

4. 过期会话缓存

~/.openclaw/agents/main/sessions/ 下的会话元数据可能缓存旧安装路径的技能引用。

rm -rf "$HOME/.openclaw/agents/main/sessions/"

目录结构

配置文件合并

OpenClaw 有两层配置，启动时合并：

关键：如果用户配置指定了 bailian-payg/qwen3.7-plus 作为主模型，但 bailian-payg provider 只在安装配置中定义，API key 来自安装配置而非用户自己的 key。需要手动同步 API key：

# 把 Hermes 的百炼 key 写到安装配置的 bailian-payg
import json
with open(r"D:\openclaw\openclaw.json", 'r') as f:
    config = json.load(f)
config['models']['providers']['bailian-payg']['apiKey'] = 'sk-xxx'
with open(r"D:\openclaw\openclaw.json", 'w') as f:
    json.dump(config, f, indent=2)

Provider 连通性验证

改完 key 后先用 curl 验证 API 能用，再起 OpenClaw：

curl -s --max-time 10 \
  https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.7-plus","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

配置生效

改完配置后必须重启 Gateway。如果 openclaw gateway restart 超时（常见），直接杀进程：

# 杀掉所有 OpenClaw 相关 node 进程
taskkill //F //FI "WINDOWTITLE eq *openclaw*"
# 然后重新启动
openclaw chat

常见故障速查

注意事项

• 不要用 npm install -g openclaw 全局安装，用本地 D:\openclaw 目录安装避免路径冲突
• PowerShell 下永远删掉 .ps1 和无扩展名 bash 脚本，只留 .cmd
• Crestodian 是维护 agent，只能回答配置/健康检查相关问题，不能正常聊天
• bailian-coding-plan 用的是 Coding Plan 端点（anthropic-messages 协议），需单独开通，不通时切到 bailian-payg
• 安装配置和用户配置的 API key 可能不同，改模型时务必确认用的是正确的 key