OpenClaw 实战部署指南：macOS 与 Windows 11 双平台一次搞定

最近在研究 AI 助手工具，发现了 OpenClaw 这个开源项目。作为一个有 20 多年开发经验的老程序员，我决定在 macOS 和 Windows 11 双系统上亲自部署一遍，把整个过程记录下来，希望能帮到同样想尝试的朋友。为什么选择 OpenClaw？- 开源可定制 - 支持多平台 - 功能丰富（AI 对话、文件操作、工具调用等）# macOS# Windows# 下载 https://no

Jason51082006

498人浏览 · 2026-04-20 22:52:22

Jason51082006 · 2026-04-20 22:52:22 发布

关键词

OpenClaw 部署
macOS 安装 OpenClaw
Windows 11 安装 OpenClaw
AI 助手本地部署
OpenClaw 踩坑
开源 AI 助手部署
OpenClaw 配置指南
OpenClaw 常见错误解决

OpenClaw 超详细安装手册（macOS + Windows 双系统）
一、通用前置要求（必看）

系统：macOS 11+ / Windows 10/11（64 位）
运行时：Node.js ≥22 LTS（推荐 24）
内存：≥2GB
网络：可访问外网（大陆建议用国内镜像）
必备：AI 模型 API Key（DeepSeek、OpenRouter、Anthropic 等）
安全：首次运行需授权「控制电脑 / 辅助功能」

二、macOS 详细安装步骤（Intel/M 系列通用）
方式 1：官方一键脚本（新手首选，自动装 Node）

打开终端
1. 快捷键：Command + 空格 → 搜「终端」

2. 执行一键安装（国内加速版）

curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry=https://registry.npmmirror.com

3. 初始化引导（onboard）脚本自动启动向导，按步骤：

选 QuickStart
输入 AI API Key
端口默认 18789
安装守护进程（开机自启）→ Yes
渠道（Telegram/Slack）→ 可跳过，后续再配

方式 2：手动 npm 安装（已有 Node）

安装 Homebrew（无则先装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装 Node 24

brew install node@24 node -v  # 验证 ≥v24.0.0

安装 OpenClaw

npm config set registry https://registry.npmmirror.com npm install -g openclaw@latest

初始化

openclaw onboard --install-daemon

macOS 权限设置（必做）

打开 系统设置 → 隐私与安全性 → 辅助功能
勾选 Terminal/iTerm2（允许控制电脑）
打开 完全磁盘访问 → 勾选终端

macOS 验证安装
openclaw --version    # 看版本 
openclaw gateway status  # 网关运行中 
openclaw dashboard    # 打开 Web UI（http://127.0.0.1:18789）

三、Windows 详细安装步骤（2 种方案）
方案 A：原生 Windows（PowerShell，新手）

以管理员身份打开 PowerShell
1. Win+S → 搜 PowerShell → 右键「以管理员身份运行」
开启执行权限（首次必做）

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

提示选 Y 确认

一键安装（国内加速）

iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

等待 5–10 分钟，自动装 Node + OpenClaw
出现 OpenClaw installed successfully 成功

2. 初始化引导

同 macOS：QuickStart → 输 API Key → 端口 18789 → 安装服务 → 渠道可跳过

方案 B：WSL2（官方推荐，稳定无坑）

管理员PowerShell 启用 WSL2

wsl --install

重启电脑 → 自动安装 Ubuntu

2. 进入 WSL2（Ubuntu）

sudo apt update && sudo apt upgrade -y

3.一键安装

curl -fsSL https://clawd.org.cn/install.sh | bash

4. 初始化

openclaw onboard --install-daemon

Windows 验证安装

openclaw --version openclaw gateway status openclaw dashboard  # 浏览器打开 http://127.0.0.1:18789

四、初始化配置（全系统通用）

1. 模型 API 配置（关键）

推荐：DeepSeek / OpenRouter（大陆稳定）
格式：

OPENCLAW_MODEL=deepseek-reasoner 
OPENCLAW_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx 
OPENCLAW_API_BASE=https://api.deepseek.com

2. 必装核心技能

# 搜索技能 
openclaw skills search browser 
openclaw skills search email 
openclaw skills search file# 安装 
openclaw skills install @openclaw/browser-control 
openclaw skills install @openclaw/email-manager 
openclaw skills install @openclaw/file-organizer

3. 启动与使用

# Web 控制面板 
openclaw dashboard  

# 终端聊天 
openclaw tui  

# 网关状态 
openclaw gateway status

我从零部署 OpenClaw：在 macOS 和 Windows 11 上的完整踩坑记录

前言

最近在研究 AI 助手工具，发现了 OpenClaw 这个开源项目。作为一个有 20 多年开发经验的老程序员，我决定在 macOS 和 Windows 11 双系统上亲自部署一遍，把整个过程记录下来，希望能帮到同样想尝试的朋友。
为什么选择 OpenClaw？ - 开源可定制 - 支持多平台 - 功能丰富（AI 对话、文件操作、工具调用等）

一、macOS 部署实战

1.1 环境准备
- 系统版本：macOS 12.7.6 - 已安装工具：Homebrew、Node.js、Git

1.2 安装步骤
步骤1：克隆仓库

git clone https://github.com/openclaw/openclaw.git 
cd openclaw

步骤2：安装依赖

npm install

1.3 配置与启动
配置文件修改

// 示例：修改  config/default.json 
{   
"port": 18789,   
"model": "deepseek/deepseek-reasoner" 
}

启动服务

npm start

1.4 验证部署成功

访问 http://localhost:18789
测试基础功能（对话、文件读取等）

二、Windows 11 部署实战

2.1 环境准备

系统版本：Windows 11 [版本号]
已安装工具：Node.js、Git、Windows Terminal

2.2 安装步骤
步骤1：使用 Git Bash 克隆仓库

git clone https://github.com/openclaw/openclaw.git 
cd openclaw

步骤2：安装依赖

npm install

2.3 配置与启动
配置调整

// Windows 可能需要调整的配置 
{
   "workspace": "C:\\Users\\你的用户名\\.openclaw\\workspace" 
}

启动服务

npm start

2.4 跨平台一致性验证

对比 macOS 和 Windows 上的功能表现
检查文件操作、网络请求等核心功能

三、性能优化与进阶配置

3.1 资源占用监控

macOS 内存/CPU 使用情况
Windows 内存/CPU 使用情况

3.2 持久化配置

如何设置开机自启动
如何配置反向代理（Nginx/Caddy）

3.3 安全加固建议

修改默认端口
设置访问密码
限制外网访问

四、踩坑经验总结

4.1 Node 版本过低

# macOS 
brew upgrade node@24  

# Windows# 下载 https://nodejs.org/ 24 LTS 重装 
```{insert\_element\_2\_}### 2. 权限不足（macOS）
```bashsudo chown -R $USER ~/.npm sudo chown -R $USER ~/.openclaw 
```{insert\_element\_3\_}### 3. Windows `spawn EINVAL` 错误 
```powershell 

# 方案1
npm update -g openclaw  
# 方案2 
notepad $PROFILE # 添加 $env:OPENCLAW_SHELL="powershell.exe" # 重启 PowerShell

4.2 端口占用（18789）

# 换端口启动 
openclaw gateway start --port 18790 
```{insert\_element\_4\_}### 5. 网络超时（大陆）
```bash 
# 永久换国内源
npm config set registry https://registry.npmmirror.com

4.3 网关启动失败

# 前台运行看日志 
openclaw gateway  
# 健康检查 
openclaw doctor 
```{insert\_element\_5\_}  
---  
# 卸载（完整清理） 
### macOS 
npm uninstall -g openclaw 
rm -rf ~/.openclaw  
### Windows 
powershell 
npm uninstall -g openclaw 
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw

4.4 给新手的建议

环境隔离：建议使用虚拟环境或 Docker
逐步验证：每完成一步就验证功能
善用日志：遇到问题先看日志输出
社区求助：GitHub Issues 和 Discord 社区很活跃

4.5 快速上手清单（30 分钟）

安装 → 初始化 → 输 API Key
装 3 个技能：浏览器、邮件、文件
打开 openclaw dashboard
测试指令：

「整理桌面文件」
「打开百度搜 AI 智能体」
「总结这篇网页」

五、避坑指南

问题一：
macos安装node时，安装过程中报错：Error: A `brew install node` process has already locked
原因：
你的电脑里已经有一个 brew install 正在运行，它把下载目录锁住了，导致新的安装无法继续。这是安装 Homebrew / Node 时最常见的锁死问题。
解决：
第一步：强制杀死所有卡住的 brew 进程
打开终端，直接运行这行：

sudo killall -9 brew node npm

输入你的电脑开机密码（输入不显示，直接回车）
第二步：删除锁文件（最关键）

sudo rm -rf /Users/MX1613/Library/Caches/Homebrew/downloads/*incomplete* 
sudo rm -rf /Users/MX1613/Library/Caches/Homebrew/locks/*

第三步：重置 Homebrew

brew cleanup 
brew update

现在重新安装 OpenClaw（一键命令）

curl -fsSL https://clawd.org.cn/install.sh | bash -s -- --registry=https://registry.npmmirror.com

问题二：
macos安装时，报错：
Error: An exception occurred within a child process:
FormulaUnavailableError: No available formula with the name "formula.jws.json".
原因：
Homebrew 本身坏了 / 索引错乱，用 brew 装 Node 会一直报错。
解决：
不用 Homebrew的方案，直接装 Node + OpenClaw，彻底跳过 brew！

一、先清理卡死的进程（必须做）
打开终端

sudo killall -9 brew node npm
sudo rm -rf ~/Library/Caches/Homebrew/*

输入电脑密码（看不见，直接回车）

二、直接安装 Node.js（不使用 brew，零报错）

curl -fsSL https://nodejs.org/dist/v22.14.0/node-v22.14.0-darwin-arm64.tar.xz -o node.tar.xz 
tar -xf node.tar.xz 
sudo cp -R node-v22.14.0-darwin-arm64/{bin,lib,include,share} /usr/local/ 
hash -rnode -v

出现 v22.14.0 就成功了！

三、安装 OpenClaw（国内加速，一次成功）
npm config set registry https://registry.npmmirror.com npm install -g openclaw@latest

问题三：
node -v提示：
-bash: /usr/local/bin/node: Bad CPU type in executable
原因：
你下载的 Node.js 是 ARM 版（M 系列芯片），但你的电脑是 Intel 芯片！
解决：

第一步：删掉错误的 Node（必须）
打开终端，逐行运行：

sudo rm -rf /usr/local/bin/node 
sudo rm -rf /usr/local/bin/npm 
sudo rm -rf /usr/local/bin/npx 
sudo rm -rf /usr/local/lib/node_modules 
rm -rf node.tar.xz node-v22*

第二步：安装 Intel 版 Node.js（正确版本）

curl -fsSL https://nodejs.org/dist/v22.14.0/node-v22.14.0-darwin-x64.tar.xz -o node.tar.xz 
tar -xf node.tar.xz 
sudo cp -R node-v22.14.0-darwin-x64/{bin,lib,include,share} /usr/local/ 
hash -r

第三步：验证 Node（这一步必须成功）

node -v
npm -v

✅ 出现版本号（v22.xx.x）就对了！

问题四：
macos安装时，报错：npm install -g openclaw@latest报错：npm error code EACCES

原因：
npm 没有权限写入系统目录，不是 OpenClaw 的问题，是 macOS 权限保护。

解决：
用 sudo 提权安装（最直接）
直接复制运行这一行 即可解决：

sudo npm install -g openclaw@latest --registry=https://registry.npmmirror.com

它会让你输入电脑开机密码（输入不显示，直接回车）。
安装成功后，继续初始化：

openclaw onboard --install-daemon

如果还报错（终极干净方案）
运行这个：

sudo chown -R $USER /usr/local/lib/node_modules 
sudo chown -R $USER /usr/local/bin

然后再装：

sudo npm install -g openclaw@latest --registry=https://registry.npmmirror.com

问题五：
windows11下执行 iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex powershell闪退了

原因：
Windows 11 下执行一键安装脚本闪退，99% 是权限 / 执行策略、网络 / TLS、脚本内部错误这三类原因导致

解决：
不闪退、能看错误的安装命令（核心）
不要直接 | iex，先下载脚本到本地再执行，这样能看到完整报错：

# 1. 下载脚本到桌面
iwr -useb https://open-claw.org.cn/install-cn.ps1 -OutFile "$env:USERPROFILE\Desktop\install-cn.ps1"
# 2. 本地执行（能看到所有报错） 
cd "$env:USERPROFILE\Desktop".\install-cn.ps1

情况 1：提示 “无法加载文件，因为在此系统上禁止运行脚本”
→ 执行：

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

然后重新运行 .\install-cn.ps1

情况 2：下载时报错 / 404 / 连接失败

检查网络 / 代理 / 翻墙（关闭代理）
再执行一遍 TLS 命令：

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

再重新下载

情况 3：脚本里报 “mkdir 权限不足 / EACCES”

确认是管理员PowerShell
重新执行：

.\install-cn.ps1

情况 4：脚本自动装 Node 失败

直接手动装 Node 22+ 再用 npm 安装（最稳兜底）：

去 nodejs.org 装 22.x LTS 一路下一步
重启 PowerShell（管理员）
执行：

npm install -g openclaw@latest --registry=https://registry.npmmirror.com

问题六：
windows11下，安装报错：错误代码: Bash/WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED
ELIFECYCLE Command failed with exit code 1.

原因：
国内定制版 openclaw-cn 强行需要 WSL/Linux 环境，普通 Windows 根本跑不起来！
使用纯 Windows 原生、无 WSL、无报错的正确安装法。

解决：
Windows 原生安装（不用 WSL！不用 Linux！）

第一步：以管理员身份打开 PowerShell

Win + S 搜索 PowerShell→ 右键 以管理员身份运行

第二步：安装 Node.js（必须）

复制运行（自动安装 Node 22 LTS）：

winget install OpenJS.NodeJS --version 22.14.0 -e

安装完重启 PowerShell（管理员）
验证：

node -v 
npm -v

出现版本号 = 成功

第三步：安装官方原版 OpenClaw（不装国内定制版！）

npm install -g openclaw --registry=https://registry.npmmirror.com

✅ 这个不会要 WSL！不会要 Bash！纯 Windows 可跑！

第四步：初始化 OpenClaw

openclaw onboard --install-daemon

初始化怎么选（照着按）

QuickStart → 回车
Skip for now (use Web UI) → 回车
端口 18789 → 回车
Y 安装守护进程
Y 确认配置

第五步：启动

openclaw gateway start

第六步：打开控制面板

openclaw dashboard

浏览器自动打开http://127.0.0.1:18789✅ 安装完成！

问题七：
windows11下，安装node时，winget install OpenJS.NodeJS --version 22.14.0 -e
winget : 无法将“winget”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。请检查名称的拼写，如果包括路径，请确保路径正确，然后再试一次。

原因：
这个错误表明你的系统无法识别 winget 命令，通常是因为 Windows Package Manager (winget) 未正确安装或未添加到系统环境变量中。

解决：

检查 winget 是否已安装

Windows 10/11 用户：winget 是 Microsoft Store 的预装应用（需 Windows 10 1809 或更高版本）。
- 打开 Microsoft Store，搜索 App Installer，确保已安装最新版本。
- 或直接访问：Microsoft Store - App Installer

手动安装（如果缺失）：
- 下载最新版 winget：https://github.com/microsoft/winget-cli/releases
- 选择 Microsoft.DesktopAppInstaller_*.msixbundle 文件安装。

2. 检查环境变量

确保 winget 的路径（通常为 C:\Program Files\WindowsApps\Microsoft.DesktopAppInstaller_*\winget.exe）已添加到系统 PATH 环境变量中。
- 步骤：
  - 右键“此电脑” → 属性 → 高级系统设置 → 环境变量。
  - 在 System Variables 中找到 Path，点击编辑。
  - 添加 winget 的实际路径（需通过 PowerShell 定位）：

powershellGet-AppxPackage -Name "Microsoft.DesktopAppInstaller" | Select-Object -ExpandProperty InstallLocation
输出路径后追加 \winget.exe（如 C:\Program Files\WindowsApps\Microsoft.DesktopAppInstaller_1.23.12345_x64__8wekyb3d8bbwe\winget.exe）。

3. 通过 PowerShell 运行 winget

如果 PATH 未配置，直接通过完整路径运行：
powershell& "C:\Program Files\WindowsApps\Microsoft.DesktopAppInstaller_*\winget.exe" install OpenJS.NodeJS --version 22.14.0 -e
（将 * 替换为实际版本号）

六、下一步计划

基于这次部署经验，我打算：

探索 OpenClaw 的插件开发
尝试与现有工作流集成
研究性能调优方案

如果你也在部署 OpenClaw 或其他 AI 工具时遇到了问题，欢迎在评论区留言讨论。我会尽力解答。
更进一步：我正计划围绕"AI 应用部署实战"做一系列深度分享，如果你对这个话题感兴趣，可以：

关注我的账号，获取后续更新
加入我的"AI 部署实战交流群"（扫码或加微信，备注"部署"）

附录：常用命令速查

# macOS/Linux 
sudo lsof -i :3000  # 查看端口占用 
ps aux | grep node  # 查找 Node 进程  

# Windows 
netstat -ano | findstr :3000  # 查看端口占用 
tasklist | findstr node       # 查找 Node 进程