OpenClaw Windows 踩坑实战指南

前置要求

Node.js 版本 ≥22.x，必须 64 位
PowerShell必须以管理员身份运行
路径全部英文，不要中文用户名、中文文件夹
准备好大模型 API Key（DeepSeek 等）
网络建议配置 npm 国内镜像

一、Windows 安装步骤

1. 安装 Node.js

官网下载 Node.js 22 LTS 版本，安装时勾选 Add to PATH。验证：

powershell

复制代码

node -v
npm -v

2. 设置 npm 国内镜像源

powershell

复制代码

npm config set registry https://registry.npmmirror.com

3. 全局安装 OpenClaw

powershell

复制代码

npm install -g openclaw@latest --allow-scripts=openclaw

如果提示openclaw不是内部或外部命令：关闭全部 PowerShell 窗口，重新打开管理员终端。

4. 初始化向导

powershell

复制代码

openclaw onboard

交互式配置要点：

同意协议 yes
Model source 选择Manual，填入你的 API‑Key
Gateway 模式：Local gateway，绑定127.0.0.1，端口默认18789
认证选择 Token，其余选项直接回车跳过。

这是 OpenClaw 初始化向导的安全免责确认页。

提示：Windows 原生版本部分功能有限，官方更推荐 WSL2；但你现在直接原生 PowerShell 继续跑也可以。

界面底部：

plaintext

复制代码

I understand this is personal‑by‑default and shared/multi‑user use requires lock‑down. Continue?
❯ Yes
  No

方向键选到 Yes，按下回车确认风险，进入下一步配置。

当前界面含义

Help make OpenClaw better? 这是遥测数据收集 ：是否把你使用的功能统计数据回传给项目方，不会上传对话内容、密钥。

选项：

No thanks：不分享（当前已经选中，推荐选这个，保护隐私）
Yes, share feature stats：分享功能统计

直接回车确认 No thanks，进入下一步。

下一步会出现：选择大模型服务商

可选：OpenAI / Anthropic / DeepSeek / Ollama（本地）等。

如果你用国内 API，优先选 DeepSeek；想跑本地大模型就选 Ollama。

选完服务商之后，就要粘贴对应的 API Key。

补充：后续如果想关闭 / 开启遥测，命令：

powershell

复制代码

openclaw telemetry off

当前界面

What should we call your first agent? 给你的第一个智能体起名字，默认填的是 main。

直接回车就用默认名字 main 即可，不用修改。

上方 QuickStart 参数说明（全部默认不用改）

Gateway port: 18789 网关端口，后面浏览器访问控制面板就是 http://127.0.0.1:18789
Gateway bind: 127.0.0.1 仅本机访问，安全；不要改成 0.0.0.0，否则外网可访问
Tailscale exposure: Off，关闭内网穿透

回车之后，下一步就是选择模型提供商、填写 API Key。

当前界面：选择模型服务商

选项列表：

OpenAI（GPT 系列）
OpenRouter
xAI(Grok)
Google
Anthropic(Claude)
More... → 里面会有 DeepSeek、Ollama 本地模型等
Skip for now 暂时跳过，先不配置 API

两种选择方案

如果你手上有国内 API 密钥（DeepSeek 等） 用方向键下移选中 More... 回车，展开更多提供商，选择 DeepSeek，之后粘贴你的 API Key。
现在没有 API Key，想先把环境跑完，后面再补密钥（推荐） 选中 Skip for now 回车，直接跳过模型配置，完成初始化流程。

跳过之后网关服务照样可以启动，打开 web 面板后再在界面里填写 API 密钥。
注意：不要直接选 OpenAI，国内网络大概率无法访问。

建议选 Skip for now，先把整套安装流程走完，后面再填 key。

当前界面：安装 DeepSeek 插件

已经选中：Download from npm (@openclaw/deepseek‑provider)，这是npm 源下载插件，推荐这个选项。

直接回车，工具会自动拉取 DeepSeek 的 provider 插件。

选项说明

Download from npm：npm 包源，国内网络成功率最高 ✅
Download from ClawHub：项目官方插件仓库，容易网络超时
Skip for now：暂时不装，后面手动装

回车下载完成后，下一步就会提示输入 DeepSeek API Key。

注意：API Key 是一长串 sk‑开头的密钥，粘贴进去，终端里不会显示明文，是正常现象。

当前状态

DeepSeek 插件安装完成，API‑key 已经录入，默认模型是 deepseek/deepseek‑v4‑pro，当前选中：Keep current。

直接回车，保持这个模型即可，不用修改。

选项说明

Keep current：沿用 v4‑pro（推荐）
Enter model manually：手动输入模型名字
Browse all models：浏览全部可用模型

回车之后，接下来会问：

是否配置聊天渠道（Telegram/Discord，不需要就跳过）
完成初始化，安装 daemon 后台守护服务

全部走完后，就可以执行命令打开 web 面板：

powershell

复制代码

openclaw dashboard

浏览器访问 http://127.0.0.1:18789，就可以在网页端和 agent 对话。

⚠️注意：Windows 上 daemon 服务如果安装失败，大概率是权限 / 杀毒拦截，可以手动启动网关：

powershell

复制代码

openclaw gateway start

当前界面：Select channel（聊天渠道）

这里是对接各类聊天软件机器人（飞书、Discord、QQBot 等），我们现在只需要网页面板使用，不需要配置任何聊天渠道。

当前选中项：Skip for now (You can add channels later via openclaw channels add) 直接回车跳过。

说明：后续想加机器人渠道，可以命令行执行：

powershell

复制代码

openclaw channels add

回车跳过之后，就进入收尾阶段：

生成配置文件
尝试安装后台守护进程（daemon）
QuickStart 向导完成

向导全部结束后，执行：

powershell

复制代码

openclaw dashboard

会自动打开浏览器，访问 http://127.0.0.1:18789，进入 OpenClaw 网页控制台，就可以和 main 智能体对话。

如果守护进程安装失败，手动启动网关：

powershell

复制代码

openclaw gateway start

当前界面：导入历史记忆

检测到你本地 ClaudeCode 的 23 条记忆记录，询问是否导入到 OpenClaw 工作区。

Yes：导入旧会话记忆
No：不导入，全新空白环境（推荐）

建议选 No，方向键切到 No，回车。

导入容易出现格式错乱，直接全新环境更稳定。

回车完成后，QuickStart 向导就全部结束。

向导结束后执行这条命令打开网页控制台：

powershell

复制代码

openclaw dashboard

浏览器会自动打开 http://127.0.0.1:18789，就可以直接和 main 智能体对话。

如果网页打不开，手动启动网关服务：

powershell

复制代码

openclaw gateway start

当前界面：Web search（联网搜索工具配置）

这个是给 Agent 增加联网搜索能力，现在不需要配置，当前选中： Skip for now (Configure later with openclaw configure --section web)

直接回车跳过。

后续想要开启联网搜索，可以执行命令：

powershell

复制代码

openclaw configure --section web

回车之后，整个 QuickStart 初始化向导就全部跑完。

向导结束后，执行命令打开网页控制台：

powershell

复制代码

openclaw dashboard

浏览器自动弹出 http://127.0.0.1:18789，即可进入 OpenClaw 面板。

网页访问失败排查：

powershell

复制代码

# 手动启动网关
openclaw gateway start
# 查看状态
openclaw status

要是想要联网搜索呢

现在正好停在搜索提供者选择界面，不用 Skip，我们选一个免 API‑key 直接能用的搜索源。

推荐二选一：

DuckDuckGo Search (experimental)：key‑free，无需密钥，直接可用
Parallel Search (Free)：免费托管 MCP 搜索，效果更好

操作：按↑↓方向键，选中 Parallel Search (Free)，按下回车。

不要选带 API key required 的，那些要申请密钥。

选中回车之后，它会自动加载搜索组件，走完向导剩余步骤。

后续如果已经跳过向导，事后补配置联网搜索的命令

powershell

复制代码

openclaw configure --section web

会重新进入搜索配置菜单，同样选 Parallel Search (Free)。

配置完成后，agent 就具备联网搜索能力，对话时会自动调用网络获取实时信息。

注意：免费搜索源有调用频率限制，频繁大量查询会被限流。

你现在终端还在这个选择界面，直接切到 Parallel Search (Free) 回车即可。

当前界面：安装缺失的技能依赖

这里是一大堆扩展技能包（截图、语音、PDF、各类第三方工具），我们暂时不需要全部安装。

直接选中第一项： Skip for now (Continue without installing dependencies) 回车跳过。

说明：

这些是附加能力，比如录音、PDF 解析、第三方平台对接；
DeepSeek 大模型 + 联网搜索已经能用，后续需要哪个技能，再单独安装即可，命令示例：

powershell

复制代码

openclaw skills install xurl

回车跳过之后，整个 QuickStart 初始化就全部结束。

向导结束后执行：

powershell

复制代码

openclaw dashboard

自动打开浏览器访问 http://127.0.0.1:18789，此时你的 agent 已经： ✅ DeepSeek‑v4‑pro 大模型 ✅ Parallel Search 免费联网搜索 ✅ 网页控制台可用

如果网页打不开，手动拉起网关：

powershell

复制代码

openclaw gateway start

🎉 Gateway service installed. 网关后台服务已经安装成功，Windows 定时任务已经注册完成，OpenClaw 初始化向导全部结束。

现在打开网页控制台

直接在终端执行：

powershell

复制代码

openclaw dashboard

会自动拉起浏览器访问：http://127.0.0.1:18789

✅ 当前已配置能力：

LLM：deepseek‑v4‑pro
联网搜索：Parallel Search (Free)
Agent：main
后台网关开机自启（Windows 计划任务）

常用调试命令（备用）

powershell

复制代码

# 查看整体运行状态
openclaw status

# 手动重启网关
openclaw gateway restart

# 检查环境、技能依赖
openclaw doctor

小提示：免费 Parallel Search 有调用频次限制，如果搜不到内容，属于正常限流，隔一会再试。

你打开网页之后，就可以直接提问，Agent 会自动调用联网搜索。

问题说明

connect ECONNREFUSED 127.0.0.1:18789

Windows 计划任务虽然安装成功，但网关服务没有正常启动，端口 18789 没有监听，所以健康检查失败。工作区配置已经全部保存好了，只是后台服务没跑起来。

第一步：手动启动网关

powershell

复制代码

openclaw gateway start

等待几秒，看输出有没有显示 Gateway listening on 127.0.0.1:18789

第二步：查看详细状态

powershell

复制代码

openclaw gateway status --deep

如果看到 running，代表成功；
如果还是没启动，看报错日志。

第三步：启动网页控制台

网关正常运行后执行：

powershell

复制代码

openclaw dashboard

浏览器访问 http://127.0.0.1:18789

常见 Windows 踩坑原因

杀毒 / Windows Defender 拦截计划任务脚本，定时任务虽然注册，但执行被阻止；

这种情况不要依赖开机自启，每次使用手动执行 openclaw gateway start 即可，不影响功能。

Node.js 版本不兼容；执行查看 node 版本

powershell

复制代码

node -v

快捷排错全套命令，直接复制依次跑

powershell

复制代码

openclaw gateway restart
openclaw gateway status --deep
openclaw dashboard

提示：就算计划任务自启失效，手动启动网关完全不影响 DeepSeek 模型、联网搜索所有能力，只是每次使用前需要敲一条启动命令。

🎉 OpenClaw TUI 终端交互界面已经成功跑起来了！ 状态：running • 2s | local ready 模型：deepseek‑v4‑pro，会话 main，已经唤醒，提示语：Wake up, my friend!

当前是终端 TUI 聊天模式，不是网页 dashboard。直接在这里输入问题就可以对话，配置的 Parallel Search 联网搜索也会生效。

切换网页控制台操作

先退出当前 TUI 界面：按 Ctrl + C
在 powershell 执行

powershell

复制代码

openclaw gateway start

等待网关启动完成 3. 再执行

powershell

复制代码

openclaw dashboard

就会弹出浏览器 WebUI（127.0.0.1:18789）

常用命令小结

powershell

复制代码

# 终端内聊天（你现在这个界面）
openclaw tui

# 启动网关后台
openclaw gateway start

# 打开网页面板
openclaw dashboard

# 查看环境与技能
openclaw doctor

小提醒：Windows 计划任务自启网关有概率被安全软件拦截，每次使用建议手动执行 openclaw gateway start，不影响全部功能。

二、Windows 原生环境高频报错（本人实战复现）

报错 1：gateway 计划任务启动，进程立刻闪退

执行openclaw gateway start，会创建 Windows 计划任务，但是进程启动瞬间直接退出。执行状态查看：

powershell

复制代码

openclaw gateway status

输出关键日志：

plaintext

复制代码

Service is loaded but not running (likely exited immediately)
connect ECONNREFUSED 127.0.0.1:18789

根因：Windows 计划任务（schtasks）运行 node 脚本存在兼容性 bug，不要使用openclaw gateway start，该命令底层调用 Windows 定时任务，极易秒退。

报错 2：openclaw tui 启动报错 `gateway disconnected: connect ECONNREFUSED 127.0.0.1:18789`

现象：TUI 界面弹出，但是持续网关断开，无法对话。

根因：Windows 版本 TUI必须依赖 gateway 网关服务，TUI 不是独立运行，网关闪退，TUI 直接连接被拒绝。

报错 3：安装 hack‑skills 渗透技能包连环报错

plaintext

复制代码

Copy‑Item : 具有指定名称的项已存在
‑Recurse‑Force : 无法将"‑Recurse‑Force"项识别为 cmdlet、函数、脚本文件或可运行程序的名称
找不到路径XXX\SCENARIOS.md，因为该路径不存在

两个问题叠加：

OpenClaw 自动生成的 powershell 脚本语法错误：‑Recurse‑Force参数没有空格，正确写法‑Recurse ‑Force。
Windows Defender 实时防护，下载下来的 hack 技能源码直接被杀毒隔离删除，源文件直接消失，复制文件时报路径不存在。

关键点：Windows 下安装 hack 类 skill 包，必须提前配置 Defender 排除目录，否则文件直接被杀掉。

需要添加排除项的目录：

plaintext

复制代码

C:\Users\你的用户名\openclaw
C:\Users\你的用户名\AppData\Local\Temp\openclaw

三、Windows 正确启动方式（绕过计划任务 bug）

❌禁止使用：openclaw gateway start（调用 Windows 计划任务，大概率秒退）

方式 A：前台手动运行 gateway 网关（可用，必须保留终端窗口）

先停止旧的计划任务服务

powershell

复制代码

openclaw gateway stop

复制你的实际 node 完整命令（从 gateway status 日志复制），示例：

powershell

复制代码

node.exe --max-old-space-size=8079 C:\Users\zouhuixin\AppData\Roaming\npm\node_modules\openclaw\dist\index.js gateway --port 18789

执行后，当前 PowerShell 窗口会被占用，千万不要关闭！ 成功输出标志：

plaintext

复制代码

Gateway listening on ws://127.0.0.1:18789

新开一个全新 PowerShell 窗口，不要关闭跑 gateway 的终端！

powershell

复制代码

# 打开TUI终端界面
openclaw tui

# 或者打开网页Dashboard
openclaw dashboard

致命提醒：运行 gateway 的窗口一旦关闭，网关立刻停止，TUI/Dashboard 全部断开。

方式 B：放弃 Windows 原生，迁移 Kali Linux（强烈推荐）

Windows 原生存在底层 bug，hack 技能包、gateway 稳定性都很差。 Kali 中 gateway 使用 systemd 后台服务，不会闪退，不需要常驻终端窗口。

Kali 快速安装命令：

bash

复制代码

# 修复apt依赖
sudo apt --fix-broken install -y
sudo apt update

# 安装node22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# npm国内镜像
npm config set registry https://registry.npmmirror.com

# 全局安装
npm install -g openclaw@latest --allow-scripts=openclaw

# 初始化，安装systemd后台服务
openclaw onboard --install-daemon

kali 常用命令

bash

复制代码

openclaw gateway status
openclaw tui
openclaw dashboard
openclaw skill install hack‑skills

四、Windows 排错清单

查看网关崩溃日志，定位 node 崩溃原因日志路径： C:\Users\zouhuixin\AppData\Local\Temp\openclaw\openclaw‑xxxx‑xx‑xx.log
排查端口 18789 占用

powershell

复制代码

netstat -ano | findstr 18789

node 内存过高崩溃，降低内存参数

powershell

复制代码

node.exe --max-old-space-size=4096 你的openclaw路径\index.js gateway --port 18789

卸载重装

powershell

复制代码

npm uninstall -g openclaw

五、总结建议

Windows 原生环境适合仅做体验，计划任务 gateway 存在硬 bug，不适合长期使用。
Windows 下想要完整使用 hack‑skills 渗透技能包，必须配置 Defender 目录排除，否则源码直接被杀毒删除。
Windows 运行 gateway 必须前台手动 node 启动，终端窗口不能关闭。
做网安 Agent 场景，优先部署在 Kali Linux，稳定性拉满，无闪退、无杀毒误杀问题。

博客结尾提示：遇到报错优先看 gateway 日志文件，大部分闪退、崩溃的真实原因都会写在日志内。

OpenClaw Windows 踩坑实战指南

前置要求

一、Windows 安装步骤

1. 安装 Node.js

2. 设置 npm 国内镜像源

3. 全局安装 OpenClaw

4. 初始化向导

当前界面含义

下一步会出现：选择大模型服务商

当前界面

当前界面：选择模型服务商

两种选择方案

当前界面：安装 DeepSeek 插件

当前状态

当前界面：Select channel（聊天渠道）

当前界面：导入历史记忆

当前界面：Web search（联网搜索工具配置）

要是想要联网搜索呢

后续如果已经跳过向导，事后补配置联网搜索的命令

当前界面：安装缺失的技能依赖

现在打开网页控制台

常用调试命令（备用）

问题说明

第一步：手动启动网关

第二步：查看详细状态

第三步：启动网页控制台

常见 Windows 踩坑原因

快捷排错全套命令，直接复制依次跑

切换网页控制台操作

常用命令小结

二、Windows 原生环境高频报错（本人实战复现）

报错 1：gateway 计划任务启动，进程立刻闪退

报错 2：openclaw tui 启动报错 gateway disconnected: connect ECONNREFUSED 127.0.0.1:18789

报错 3：安装 hack‑skills 渗透技能包连环报错

三、Windows 正确启动方式（绕过计划任务 bug）

方式 A：前台手动运行 gateway 网关（可用，必须保留终端窗口）

方式 B：放弃 Windows 原生，迁移 Kali Linux（强烈推荐）

四、Windows 排错清单

五、总结建议

报错 2：openclaw tui 启动报错 `gateway disconnected: connect ECONNREFUSED 127.0.0.1:18789`