Win11 部署 OpenClaw 全流程：避开 token / shim / .env 三大坑

痛点先说 ：Windows 上折腾 OpenClaw 最大的坑不是"装不上"，而是 token / shim / .env 这些细节导致 Dashboard 卡住。你以为两分钟就能起，实际很容易在最后一步卡半天。

OpenClaw 是一个开源 AI 代理/助手项目，通过 Gateway 把多种渠道接入代理能力，Dashboard 用来聊天、配置和调试。

在 AI 生成领域的定位上，它更像"连接器 + 调度台"：把模型、Agent、Workflow 和外部渠道串起来，让模型不只是"会回答"，而是"能执行"。

结论先说：用官方安装脚本 + 包装脚本，10 分钟内可以完整跑通 Gateway + Dashboard。对比自己手动装，至少省 1 小时试错。

OpenClaw 在 AI 生态里的位置

如果把 AI 生成看成一条生产线：

模型是大脑（LLM/多模态）
Agent是执行者（具备工具调用与记忆）
Workflow是流程编排（把多步任务变成标准流程）
OpenClaw 负责把这些能力接到外部渠道（聊天入口/业务系统/工具链）

简单理解：OpenClaw 把"会答题的模型"，变成"能在真实场景里跑起来的系统"。

环境准备（直接上手）

Windows 11
PowerShell 5.1+（推荐 7）
Node.js 22+

第一步：一条命令安装（快速上手）

OpenClaw 默认不会自动读取 .env，而 Windows 会优先命中 npm 的 shim。官方安装脚本 + 包装脚本 是目前最稳的路线：会生成配置、生成 token，并规避 Windows 兼容坑。

powershell 复制代码

powershell -ExecutionPolicy Bypass -File scripts/windows/install-openclaw.ps1

为什么有效（简要理解即可）：

自动生成 %USERPROFILE%\.openclaw-main\.env 和 openclaw.json
自动生成 OPENCLAW_GATEWAY_TOKEN
内置常见模型配置

第二步：只写 .env，不要碰 openclaw.json（避免冲突）

路径：

复制代码

%USERPROFILE%\.openclaw-main\.env

只填你需要的 Key（示例）：

复制代码

QWEN_API_KEY=...
DEEPSEEK_API_KEY=...
GLM_API_KEY=...
MINIMAX_API_KEY=...
OPENAI_API_KEY=...
GEMINI_API_KEY=...

对比/反差 ：把 Key 写进 openclaw.json 的同学，后面更容易出"token 配置异常"，实际是脚本读取顺序冲突。

进阶说明 ：OpenClaw 默认不会自动读取 .env，包装脚本先加载环境变量再调用命令，避免"看似配置了却读不到"的问题。

第三步：用包装脚本启动（关键步骤）

powershell 复制代码

cd C:\openclaw\scripts\windows
.\openclaw-wrap.ps1 -DebugEnv
.\openclaw-wrap.ps1 models list --all --provider deepseek --plain
.\openclaw-wrap.ps1 models set deepseek/deepseek-chat
.\openclaw-wrap.ps1 gateway --port 18789 --auth token
.\openclaw-wrap.ps1 dashboard --no-open

浏览器打开输出的带 ?token=... 的地址。

成果验证（你应该看到的结果）

效果：Gateway 常驻、Dashboard 可访问、模型可切换。实际从安装到可用大约 10 分钟。

进阶提示：如果你需要长期稳定运行，可将 Gateway 独立为常驻任务/服务，再单独启动 Dashboard 进行调试。

常见坑（最容易踩的 4 个）

1) unauthorized: token_missing

原因：打开了不带 token 的 URL。

解决：用 openclaw-wrap.ps1 dashboard --no-open 输出的带 token 地址。

2) Gateway auth is set to token, but no token is configured

原因：.env 没有 OPENCLAW_GATEWAY_TOKEN。

解决：确保 .env 有 token，并用包装脚本启动 Gateway。

3) gateway --force 报 lsof not found

原因：这是 Unix 工具。

解决：Windows 下用 openclaw-wrap.ps1（已兼容）。

4) openclaw.ps1 -DebugEnv 报 unknown option

原因：执行了 npm shim，不是仓库脚本。

解决：用 C:\openclaw\scripts\windows\openclaw-wrap.ps1。

结尾

如果你也在 Windows 上折腾 OpenClaw，直接照这个流程来，省掉大量试错成本。后续我会继续写：

多模型切换的最佳实践
本地 Gateway 稳定性优化
与更多工具链的集成方案

觉得有用欢迎收藏/关注，我会持续输出可落地的技术实战。

作者简介： 10年+视频技术、后端架构、AI应用开发经验，曾任某互联网大厂技术专家。对AI编程工具、云原生架构、视频处理技术有深入研究。

合作请加WX：hbstream
（http://haibindev.cnblogs.com），转载请注明作者和出处