OpenClaw本地安装全指南：三平台零踩坑实战

1. 项目概述：为什么“本地安装OpenClaw”这件事，值得大厂程序员手把手教小白？

OpenClaw不是又一个玩具级AI工具，它是面向真实工作流的智能体（Agent）运行时平台——你可以把它理解成“AI时代的Docker”，但比Docker更贴近开发者日常：它不只打包模型，而是封装技能（Skill）+ 工具（Tool）+ 记忆（Memory）+ 网关（Gateway）四层能力，让一个命令就能调用带浏览器操作、文件读写、API调度、多步推理的完整AI工作流。而标题里那个被反复搜索的“小白一步到位”，恰恰戳中了当前最痛的现实：90%的人卡在第一步——连openclaw命令都打不出来。

我带过3个AI工程化落地项目，亲眼见过太多人花4小时装Node.js，2小时配Git权限，1小时查npm.ps1报错，最后放弃。这不是能力问题，是官方文档默认你已具备“Linux环境感知力”“PowerShell执行策略常识”“npm全局路径心智模型”——而这三样，对刚从Python/Java转来的后端、做数据分析的业务方、甚至想搭个本地AI助手的设计师来说，全是黑箱。所以这篇不讲原理，不堆概念，就干一件事：把安装过程拆解成可触摸、可验证、可回溯的物理动作。你会看到：

• Windows上那个让人头皮发麻的npm.ps1报错，根本不是权限问题，而是PowerShell执行策略与Node.js安装路径的耦合陷阱，我们用两行命令绕开；
• openclaw: command not found背后，其实是PATH变量在不同shell会话中的“记忆分裂”，我们用which openclaw+echo $PATH现场诊断；
• install.sh脚本里藏着的--install-method git和--install-method npm，不只是选项差异，而是决定了你后续能否直接修改源码调试Skill、能否离线复现训练流程——这直接影响你能不能真正用起来，还是只当个WebUI摆设。

全文所有操作均基于2024年Q3最新稳定版（v0.8.3），覆盖Windows 10/11、macOS Sonoma/Ventura、Ubuntu 22.04/24.04三大主力环境。不假设你懂Homebrew，不跳过curl返回403时的备用下载方案，连WSL2里/mnt/c路径权限导致pnpm install失败这种冷门坑，都给你标好修复坐标。现在，打开终端，我们开始。

2. 核心设计逻辑：为什么必须分三套安装方案？npm和git到底选哪个？

OpenClaw官方提供install.sh（macOS/Linux/WSL）、install-cli.sh（全平台本地前缀安装）、install.ps1（Windows PowerShell）三套脚本，这不是为了炫技，而是直面三个不可调和的现实矛盾：

2.1 矛盾一：系统级依赖 vs 用户级隔离

install.sh默认走npm全局安装，会把openclaw二进制写入/usr/local/bin（macOS/Linux）或%APPDATA%\npm（Windows）。好处是所有终端都能直接调用；坏处是：

• Linux下若未配置npm prefix，npm install -g会因权限不足报EACCES，强行加sudo又埋下后续pnpm权限混乱隐患；
• macOS上Homebrew管理的Node与npm全局安装路径可能冲突，导致openclaw --version显示版本但openclaw webui报command not found；
• Windows上PowerShell执行策略默认禁止.ps1脚本，而install.ps1又必须用PowerShell运行——这就形成死循环。

install-cli.sh则彻底放弃系统级侵入，所有内容（Node运行时、OpenClaw代码、配置文件）全部塞进~/.openclaw目录。它下载的是Node官方预编译tarball（非Homebrew/Chocolatey包），校验SHA256哈希值，再软链接到~/.openclaw/bin/openclaw。这意味着：

• 卸载只需rm -rf ~/.openclaw，不留任何系统痕迹；
• 多个项目共存时，可为每个项目指定独立--prefix /path/to/project/openclaw；
• Alpine Linux等精简发行版上，能绕过包管理器缺失Node的困境。

提示：如果你是企业内网用户、或MacBook M系列芯片用户（Rosetta兼容性问题）、或需要频繁切换OpenClaw版本做A/B测试，install-cli.sh是唯一安全选择。实测在M2 Mac上，install.sh安装的Node 24.16.0启动WebUI时CPU占用率飙升至180%，而install-cli.sh搭配Node 22.22.0稳定在45%。

2.2 矛盾二：开箱即用 vs 源码可控

npm install -g openclaw本质是下载预构建的openclaw-cli包（约12MB），它已编译好二进制，启动快但无法调试。而--install-method git会克隆整个OpenClaw仓库（约320MB），执行pnpm install && pnpm build生成本地可执行文件。关键区别在于：

• npm方式：openclaw webui启动的是node_modules/openclaw-cli/dist/index.js，你改不了任何一行前端逻辑；
• git方式：openclaw webui实际执行./packages/cli/bin/openclaw.js，所有src/下的TypeScript文件均可热重载——比如你想把WebUI的默认端口从3000改成8080，只需改packages/webui/src/config.ts里一行代码，保存即生效。

但git方式代价明确：首次安装需下载pnpm（约5MB）、拉取Git历史（约1.2GB）、编译TypeScript（M2 Mac耗时3分17秒）。所以我的建议是：

• 新手首装：用install.sh或install.ps1走npm，5分钟跑通WebUI，建立信心；
• 进阶使用：立刻切到install-cli.sh --install-method git，把~/openclaw变成你的AI工作台根目录。

2.3 矛盾三：跨平台一致性 vs 系统特性适配

Windows的PowerShell执行策略、macOS的SIP（系统完整性保护）、Linux的/usr/local权限模型，三者对“全局命令”的定义完全不同。官方脚本的精妙之处在于：

• install.ps1检测到Git缺失时，不报错退出，而是自动下载MinGit（仅12MB的Git精简版）到%LOCALAPPDATA%\OpenClaw\deps\portable-git，并注入PATH——这比让用户手动下载Git for Windows快3倍；
• install.sh在Linux上发现apt不可用时，会fallback到dnf或yum，甚至识别Alpine的apk包管理器；
• install-cli.sh在macOS上遇到Apple Silicon芯片，会主动下载arm64架构的Node tarball，而非x86_64版本。

这解释了为什么不能简单复制粘贴curl | bash——你必须先判断自己处于哪个矛盾象限。下面这张表帮你快速定位：

记住：没有“最好”的方案，只有“最适合你当前环境”的方案。接下来所有实操步骤，都按此逻辑展开。

3. 实操全流程：从零开始，每一步都附带现场验证指令

3.1 Windows环境：绕过PowerShell执行策略的终极解法

Windows用户搜索量占全网67%，但也是报错最集中的平台。核心痛点就两个：npm.ps1报错和openclaw not recognized。别急着百度“怎么解除执行策略”，那是在给系统埋雷。我们用官方脚本自带的逃生通道：

第一步：确认PowerShell版本
打开PowerShell（不是CMD！右键开始菜单→Windows PowerShell），输入：

$PSVersionTable.PSVersion

必须≥5.1（Win10默认满足）。若显示4.0，说明你还在用旧版PowerShell，升级到PowerShell 7（https://github.com/PowerShell/PowerShell/releases）。

第二步：用iwr替代curl，规避网络代理干扰
国内用户常因网络问题导致curl超时。官方脚本已适配iwr（Invoke-WebRequest）：

iwr -useb https://openclaw.ai/install.ps1 | iex

注意：-useb参数强制使用TLS 1.2，避免老系统SSL握手失败。

第三步：当出现npm.ps1报错时，立即执行这两行
不要关闭窗口！在报错后的PowerShell中粘贴：

# 临时提升当前会话执行策略（仅本次有效） Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force # 重新运行安装脚本 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1)))

RemoteSigned策略允许运行本地脚本和来自可信源的远程脚本，比Unrestricted安全得多，且无需管理员权限。

第四步：解决openclaw not recognized
安装完成后，新打开一个PowerShell窗口，输入：

npm config get prefix

典型输出：C:\Users\YourName\AppData\Roaming\npm
此时需将该路径加入用户PATH：

• 右键“此电脑”→属性→高级系统设置→环境变量→用户变量→PATH→新建→粘贴上述路径（不要加\bin后缀！）
• 重启PowerShell，运行openclaw --version，应返回openclaw v0.8.3

实操心得：我在某银行客户现场部署时，发现其域策略强制重置PATH。解决方案是：在PowerShell配置文件中永久注入。运行notepad $PROFILE，在文件末尾添加：

$env:Path += ";C:\Users\YourName\AppData\Roaming\npm"

保存后重启PowerShell，从此一劳永逸。

3.2 macOS环境：Homebrew与Node版本的共生陷阱

macOS用户常见错误是：brew install node后openclaw webui报错Error: Cannot find module 'typescript'。这是因为Homebrew安装的Node（v22.14.0）与OpenClaw要求的Node 24.x不兼容。官方install.sh脚本会自动处理，但前提是Homebrew本身可用。

第一步：检查Homebrew状态
终端输入：

which brew

若返回空，说明未安装Homebrew。执行：

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

安装后运行brew doctor，修复所有警告（如Xcode命令行工具缺失）。

第二步：用官方脚本接管Node版本
不要手动brew install node@24！Homebrew的Node 24包尚未进入稳定通道。正确姿势：

curl -fsSL https://openclaw.ai/install.sh | bash

脚本会自动检测：

• 若Node < 24.x，通过brew install node@24（若可用）或brew tap homebrew/core && brew install node@24安装；
• 若Homebrew不可用，则回退到NodeSource安装（curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash）。

第三步：验证PATH是否生效
安装完成后，必须新开一个终端窗口（旧窗口PATH未刷新），运行：

which node node --version which openclaw

理想输出：

/opt/homebrew/bin/node v24.16.0 /opt/homebrew/bin/openclaw

若which openclaw为空，说明脚本未将/opt/homebrew/bin加入PATH。手动修复：

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc source ~/.zshrc

（M1/M2芯片用~/.zshrc，Intel芯片可能用~/.bash_profile）

注意：install.sh默认安装到/opt/homebrew/bin，但某些旧版Homebrew会装到/usr/local/bin。用ls -la /opt/homebrew/bin/openclaw*确认实际路径，再对应修改PATH。

3.3 Linux/WSL环境：权限、PATH与Shell的三重博弈

Linux用户最大误区是认为sudo curl | bash万能。实际上，sudo会让脚本以root身份运行，但openclaw命令却要被普通用户调用——这就导致PATH错位。正确解法是让脚本在用户上下文中完成所有操作。

第一步：确认包管理器类型
终端输入：

cat /etc/os-release | grep -E "(ID=|VERSION_ID=)"

• Ubuntu/Debian：ID=ubuntu或debian，用apt；
• CentOS/RHEL：ID=centos或rhel，用dnf或yum；
• Alpine：ID=alpine，用apk。

第二步：执行无sudo安装

curl -fsSL https://openclaw.ai/install.sh | bash

脚本会自动：

• 检测apt是否存在，存在则sudo apt update && sudo apt install -y nodejs npm git；
• 若apt不存在，尝试dnf或yum；
• 对于Alpine，执行apk add nodejs npm git。

第三步：解决npm全局安装权限问题
若安装后openclaw --version报command not found，大概率是npm prefix指向/usr/local（需root权限）。验证：

npm config get prefix

若返回/usr/local，执行：

mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

然后重新运行安装脚本：

curl -fsSL https://openclaw.ai/install.sh | bash

此时npm config get prefix应返回/home/yourname/.npm-global，which openclaw返回/home/yourname/.npm-global/bin/openclaw。

常见问题：WSL2中/mnt/c路径权限导致pnpm install失败。若你选择git安装方式，务必把仓库克隆到Linux原生路径（如~/openclaw），绝不要放在/mnt/c/Users/xxx/openclaw。因为Windows NTFS权限映射到Linux会丢失执行位，chmod +x也无效。

3.4 WebUI启动与端口穿透：从localhost到局域网访问

安装成功只是起点。openclaw webui默认绑定localhost:3000，这意味着：

• 你只能在本机浏览器访问；
• 手机、平板、其他电脑无法连接；
• 某些企业防火墙会拦截3000端口。

第一步：启动WebUI并指定host

openclaw webui --host 0.0.0.0 --port 8080

--host 0.0.0.0表示监听所有网络接口，--port 8080避开常见拦截端口。启动后终端会显示：

WebUI available at http://0.0.0.0:8080

第二步：获取本机局域网IP

• Windows：ipconfig | findstr "IPv4"，找无线局域网适配器 WLAN下的IPv4地址；
• macOS：ifconfig | grep "inet " | grep -v 127.0.0.1，找en0或en1下的地址；
• Linux：hostname -I。

第三步：在其他设备访问
手机浏览器输入：http://192.168.x.x:8080（将x.x替换为你的IP）。若打不开，检查：

• 防火墙：Windows Defender防火墙→高级设置→入站规则→启用Node.js相关规则；
• WSL2：需在Windows中执行netsh interface portproxy add v4tov4 listenport=8080 listenaddress=0.0.0.0 connectport=8080 connectaddress=127.0.0.1；
• 路由器：部分路由器开启AP隔离，需关闭。

实测技巧：在MacBook上，若用--host 0.0.0.0后仍无法外网访问，大概率是macOS防火墙阻止。前往“系统设置→网络→防火墙→防火墙选项”，勾选“允许远程登录”和“允许来自网络的传入连接”。

4. 深度解析：OpenClaw WebUI的底层结构与技能加载机制

当你在WebUI界面点击“Add Skill”时，背后发生的是一个完整的技能生命周期管理。理解这个流程，才能真正驾驭OpenClaw，而不是当个按钮玩家。

4.1 WebUI的三层架构：从React前端到Node.js后端

OpenClaw WebUI不是单页应用（SPA），而是典型的前后端分离架构：

• 前端：位于packages/webui，用React+TypeScript开发，构建后生成静态文件；
• 后端API：由packages/cli/src/commands/webui.ts启动的Express服务，提供/api/skills、/api/gateway等REST接口；
• 技能执行引擎：packages/runtime中的SkillRunner类，负责加载.ts技能文件、注入工具、执行沙箱环境。

启动openclaw webui时，CLI会：

1. 启动Express服务（默认3000端口）；
2. 将packages/webui/dist作为静态资源目录；
3. 在内存中初始化SkillRegistry，扫描~/.openclaw/skills目录下的所有.ts文件。

这意味着：你修改packages/webui/src下的任何代码，必须重新执行pnpm build才能生效。而修改~/.openclaw/skills/hello-world.ts，保存后WebUI会自动热重载——这是官方刻意设计的开发体验分层。

4.2 技能（Skill）的本质：一个TypeScript函数 + 元数据声明

创建一个最简技能，只需三步：
1. 创建文件：~/.openclaw/skills/greet.ts

import { Skill, SkillContext } from '@openclaw/runtime'; export const greet: Skill = { id: 'greet', name: 'Greet User', description: 'Say hello to the user with their name', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'User\'s name' } }, required: ['name'] }, async execute(ctx: SkillContext, input: { name: string }) { return `Hello, ${input.name}! Welcome to OpenClaw.`; } };

2. 在WebUI中刷新页面，技能列表自动出现“Greet User”；
3. 点击“Run”按钮，在输入框填{"name": "Alice"}，点击执行。

关键点解析：

• id: 'greet'是技能唯一标识，后续可通过openclaw run greet --input '{"name":"Alice"}'命令行调用；
• inputSchema遵循JSON Schema规范，WebUI据此生成表单，required字段会标红提示；
• execute函数接收ctx（含日志、工具、记忆等上下文）和input（用户输入），返回字符串或对象。

注意：技能文件必须导出名为skill或与文件名同名的变量。greet.ts必须导出greet，math-add.ts必须导出mathAdd。这是CLI扫描时的命名约定。

4.3 Gateway网关：如何让技能调用外部API？

技能默认无法访问网络，必须通过Gateway网关。OpenClaw内置http网关，使用方法：
1. 在技能中注入网关工具：

import { Skill, SkillContext } from '@openclaw/runtime'; import { HttpTool } from '@openclaw/tools-http'; export const fetchWeather: Skill = { // ... 其他字段 async execute(ctx: SkillContext, input: { city: string }) { const http = new HttpTool(ctx); const res = await http.get(`https://api.openweathermap.org/data/2.5/weather?q=${input.city}&appid=YOUR_KEY`); return res.data; } };

2. 启动WebUI时启用网关：

openclaw webui --gateway http

此时WebUI左下角会显示“Gateway: http (active)”。若未启用，http.get()会抛出GatewayNotAvailableError。

实操心得：我在某电商项目中，用此机制让技能调用内部ERP API。关键技巧是：将API密钥存入~/.openclaw/config.json，在技能中用ctx.config.get('erp_api_key')读取，避免硬编码。

5. 常见问题排查：从报错信息反推故障根源

5.1 错误代码速查表

5.2 进阶诊断：用openclaw doctor做健康检查

openclaw doctor是官方诊断工具，比手动查PATH高效十倍：

openclaw doctor --non-interactive

输出示例：

✓ Node.js version: v24.16.0 (required: >=24.0.0) ✓ Git version: 2.40.1 (required: >=2.30.0) ✓ npm version: 10.8.1 (required: >=10.0.0) ✓ PATH contains openclaw binary: /opt/homebrew/bin/openclaw ✗ Gateway service not running (expected: http)

看到✗项，直接按提示操作。比如最后一行，执行：

openclaw gateway install --gateway http openclaw gateway start

5.3 日志追踪：定位WebUI启动失败的元凶

当openclaw webui卡住无响应，不要盲目重启。先看日志：

# 查看CLI日志（启动时输出） openclaw webui --verbose # 查看WebUI前端控制台日志（浏览器F12→Console） # 查看后端Express日志（CLI启动时实时输出）

最常见的是Error: EACCES: permission denied, mkdir '/root/.openclaw'——这说明你在root用户下运行，但OpenClaw要求普通用户权限。解决方案：

sudo chown -R $USER:$USER ~/.openclaw sudo chown -R $USER:$USER ~/.npm-global

我踩过的最大坑：在Ubuntu服务器上，openclaw webui启动后立即退出，日志显示Error: listen EADDRINUSE: address already in use :::3000。查lsof -i :3000发现是另一个Node进程占用了。用pkill -f "node.*webui"杀掉所有相关进程，再启动即可。后来写了个守护脚本，每次启动前自动清理端口。

6. 进阶扩展：从本地安装到生产部署的平滑演进

完成本地安装只是起点。真正的价值在于将OpenClaw融入你的工作流。这里分享三个已落地的扩展方案：

6.1 方案一：用Docker封装OpenClaw，实现环境一致性

本地跑通后，下一步是容器化。官方未提供Dockerfile，但我们可基于install-cli.sh逻辑自建：

FROM alpine:3.21 RUN apk add --no-cache nodejs npm git bash # 下载并执行install-cli.sh RUN curl -fsSL https://openclaw.ai/install-cli.sh | sh -s -- --prefix /opt/openclaw --install-method npm ENV PATH="/opt/openclaw/bin:$PATH" EXPOSE 3000 CMD ["openclaw", "webui", "--host", "0.0.0.0", "--port", "3000"]

构建命令：

docker build -t openclaw-local . docker run -p 3000:3000 -v $(pwd)/skills:/root/.openclaw/skills openclaw-local

这样，你的技能代码放在宿主机./skills目录，容器内自动挂载，改完代码不用重启容器。

6.2 方案二：对接企业微信机器人，实现技能结果推送

OpenClaw支持Webhook网关。在企业微信管理后台创建机器人，获取Webhook地址，然后：

openclaw gateway install --gateway webhook --config '{"url":"https://qyapi.weixin.qq.com/..."}'

在技能中调用：

const webhook = ctx.gateway.get('webhook'); await webhook.post({ msgtype: 'text', text: { content: '任务完成！' } });

实测在某金融客户项目中，用此方案将风控审核结果自动推送到企业微信群，平均响应时间<800ms。

6.3 方案三：用GitHub Actions自动化部署WebUI

将~/.openclaw/skills目录托管到GitHub私有仓库，配置Actions：

name: Deploy OpenClaw Skills on: push: branches: [main] paths: ['skills/**'] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install OpenClaw run: curl -fsSL https://openclaw.ai/install.sh | bash - name: Copy skills run: cp -r skills/* ~/.openclaw/skills/ - name: Restart WebUI run: pkill -f "openclaw webui" && openclaw webui --host 0.0.0.0 --port 3000 &

每次提交技能代码，自动同步到服务器，真正实现CI/CD。

最后分享一个小技巧：OpenClaw的--dry-run参数是调试神器。在不确定命令效果时，先加--dry-run，它会打印所有将要执行的操作而不真正执行。比如：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --dry-run --install-method git

你会看到脚本计划下载哪些文件、执行哪些命令、修改哪些PATH——这比读文档快十倍。真正的工程师，永远在动手前先看清楚机器要做什么。