1. 项目概述为什么“本地安装OpenClaw”这件事值得大厂程序员手把手教小白OpenClaw不是又一个玩具级AI工具它是面向真实工作流的智能体Agent运行时平台——你可以把它理解成“AI时代的Docker”但比Docker更贴近开发者日常它不只打包模型而是封装技能Skill 工具Tool 记忆Memory 网关Gateway四层能力让一个命令就能调用带浏览器操作、文件读写、API调度、多步推理的完整AI工作流。而标题里那个被反复搜索的“小白一步到位”恰恰戳中了当前最痛的现实90%的人卡在第一步——连openclaw命令都打不出来。我带过3个AI工程化落地项目亲眼见过太多人花4小时装Node.js2小时配Git权限1小时查npm.ps1报错最后放弃。这不是能力问题是官方文档默认你已具备“Linux环境感知力”“PowerShell执行策略常识”“npm全局路径心智模型”——而这三样对刚从Python/Java转来的后端、做数据分析的业务方、甚至想搭个本地AI助手的设计师来说全是黑箱。所以这篇不讲原理不堆概念就干一件事把安装过程拆解成可触摸、可验证、可回溯的物理动作。你会看到Windows上那个让人头皮发麻的npm.ps1报错根本不是权限问题而是PowerShell执行策略与Node.js安装路径的耦合陷阱我们用两行命令绕开openclaw: command not found背后其实是PATH变量在不同shell会话中的“记忆分裂”我们用which openclawecho $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.shmacOS/Linux/WSL、install-cli.sh全平台本地前缀安装、install.ps1Windows PowerShell三套脚本这不是为了炫技而是直面三个不可调和的现实矛盾2.1 矛盾一系统级依赖 vs 用户级隔离install.sh默认走npm全局安装会把openclaw二进制写入/usr/local/binmacOS/Linux或%APPDATA%\npmWindows。好处是所有终端都能直接调用坏处是Linux下若未配置npm prefixnpm install -g会因权限不足报EACCES强行加sudo又埋下后续pnpm权限混乱隐患macOS上Homebrew管理的Node与npm全局安装路径可能冲突导致openclaw --version显示版本但openclaw webui报command not foundWindows上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/openclawAlpine 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、编译TypeScriptM2 Mac耗时3分17秒。所以我的建议是新手首装用install.sh或install.ps1走npm5分钟跑通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——你必须先判断自己处于哪个矛盾象限。下面这张表帮你快速定位你的场景推荐方案关键命令验证方式Windows 10/11公司电脑禁用PowerShell脚本install-cli.shcurl -fsSL https://openclaw.ai/install-cli.sh | bashls ~/.openclaw/bin/openclaw*应存在.cmd文件macOS已装Homebrew且常用Terminalinstall.shcurl -fsSL https://openclaw.ai/install.sh | bashwhich openclaw返回/opt/homebrew/bin/openclawUbuntu服务器无root权限install-cli.sh --prefix $HOME/myopenclawcurl ... | bash -s -- --prefix $HOME/myopenclawecho $HOME/myopenclaw/bin必须在PATH中需要修改WebUI源码如增加自定义按钮install.sh --install-method gitcurl ... | bash -s -- --install-method gitls ~/openclaw/packages/webui/src/components/应存在React组件记住没有“最好”的方案只有“最适合你当前环境”的方案。接下来所有实操步骤都按此逻辑展开。3. 实操全流程从零开始每一步都附带现场验证指令3.1 Windows环境绕过PowerShell执行策略的终极解法Windows用户搜索量占全网67%但也是报错最集中的平台。核心痛点就两个npm.ps1报错和openclaw not recognized。别急着百度“怎么解除执行策略”那是在给系统埋雷。我们用官方脚本自带的逃生通道第一步确认PowerShell版本打开PowerShell不是CMD右键开始菜单→Windows PowerShell输入$PSVersionTable.PSVersion必须≥5.1Win10默认满足。若显示4.0说明你还在用旧版PowerShell升级到PowerShell 7https://github.com/PowerShell/PowerShell/releases。第二步用iwr替代curl规避网络代理干扰国内用户常因网络问题导致curl超时。官方脚本已适配iwrInvoke-WebRequestiwr -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安装的Nodev22.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 node24Homebrew的Node 24包尚未进入稳定通道。正确姿势curl -fsSL https://openclaw.ai/install.sh | bash脚本会自动检测若Node 24.x通过brew install node24若可用或brew tap homebrew/core brew install node24安装若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 ~/.zshrcM1/M2芯片用~/.zshrcIntel芯片可能用~/.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/DebianIDubuntu或debian用aptCentOS/RHELIDcentos或rhel用dnf或yumAlpineIDalpine用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-globalwhich 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并指定hostopenclaw webui --host 0.0.0.0 --port 8080--host 0.0.0.0表示监听所有网络接口--port 8080避开常见拦截端口。启动后终端会显示WebUI available at http://0.0.0.0:8080第二步获取本机局域网IPWindowsipconfig | findstr IPv4找无线局域网适配器 WLAN下的IPv4地址macOSifconfig | grep inet | grep -v 127.0.0.1找en0或en1下的地址Linuxhostname -I。第三步在其他设备访问手机浏览器输入http://192.168.x.x:8080将x.x替换为你的IP。若打不开检查防火墙Windows Defender防火墙→高级设置→入站规则→启用Node.js相关规则WSL2需在Windows中执行netsh interface portproxy add v4tov4 listenport8080 listenaddress0.0.0.0 connectport8080 connectaddress127.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用ReactTypeScript开发构建后生成静态文件后端API由packages/cli/src/commands/webui.ts启动的Express服务提供/api/skills、/api/gateway等REST接口技能执行引擎packages/runtime中的SkillRunner类负责加载.ts技能文件、注入工具、执行沙箱环境。启动openclaw webui时CLI会启动Express服务默认3000端口将packages/webui/dist作为静态资源目录在内存中初始化SkillRegistry扫描~/.openclaw/skills目录下的所有.ts文件。这意味着你修改packages/webui/src下的任何代码必须重新执行pnpm build才能生效。而修改~/.openclaw/skills/hello-world.ts保存后WebUI会自动热重载——这是官方刻意设计的开发体验分层。4.2 技能Skill的本质一个TypeScript函数 元数据声明创建一个最简技能只需三步1. 创建文件~/.openclaw/skills/greet.tsimport { 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必须导出greetmath-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}appidYOUR_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 错误代码速查表报错信息根本原因一键修复命令npm : 无法加载文件 ... npm.ps1PowerShell执行策略禁止脚本Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Forceopenclaw: command not foundPATH未包含openclaw所在目录echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrcError: Cannot find module typescriptNode版本与OpenClaw不兼容用install.sh重装确保Node≥24.xopenclaw webui: command not foundCLI未正确安装或PATH错位npm list -g openclaw-cli若为空则重装WebSocket connection failedWebUI端口被占用或防火墙拦截lsof -i :3000查进程kill -9 PID或换端口--port 8080Failed to load skill: SyntaxError技能TS文件有语法错误cd ~/.openclaw/skills tsc --noEmit greet.ts验证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 start5.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私有仓库配置Actionsname: Deploy OpenClaw Skills on: push: branches: [main] paths: [skills/**] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - 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——这比读文档快十倍。真正的工程师永远在动手前先看清楚机器要做什么。
OpenClaw本地安装全指南：三平台零踩坑实战
1. 项目概述为什么“本地安装OpenClaw”这件事值得大厂程序员手把手教小白OpenClaw不是又一个玩具级AI工具它是面向真实工作流的智能体Agent运行时平台——你可以把它理解成“AI时代的Docker”但比Docker更贴近开发者日常它不只打包模型而是封装技能Skill 工具Tool 记忆Memory 网关Gateway四层能力让一个命令就能调用带浏览器操作、文件读写、API调度、多步推理的完整AI工作流。而标题里那个被反复搜索的“小白一步到位”恰恰戳中了当前最痛的现实90%的人卡在第一步——连openclaw命令都打不出来。我带过3个AI工程化落地项目亲眼见过太多人花4小时装Node.js2小时配Git权限1小时查npm.ps1报错最后放弃。这不是能力问题是官方文档默认你已具备“Linux环境感知力”“PowerShell执行策略常识”“npm全局路径心智模型”——而这三样对刚从Python/Java转来的后端、做数据分析的业务方、甚至想搭个本地AI助手的设计师来说全是黑箱。所以这篇不讲原理不堆概念就干一件事把安装过程拆解成可触摸、可验证、可回溯的物理动作。你会看到Windows上那个让人头皮发麻的npm.ps1报错根本不是权限问题而是PowerShell执行策略与Node.js安装路径的耦合陷阱我们用两行命令绕开openclaw: command not found背后其实是PATH变量在不同shell会话中的“记忆分裂”我们用which openclawecho $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.shmacOS/Linux/WSL、install-cli.sh全平台本地前缀安装、install.ps1Windows PowerShell三套脚本这不是为了炫技而是直面三个不可调和的现实矛盾2.1 矛盾一系统级依赖 vs 用户级隔离install.sh默认走npm全局安装会把openclaw二进制写入/usr/local/binmacOS/Linux或%APPDATA%\npmWindows。好处是所有终端都能直接调用坏处是Linux下若未配置npm prefixnpm install -g会因权限不足报EACCES强行加sudo又埋下后续pnpm权限混乱隐患macOS上Homebrew管理的Node与npm全局安装路径可能冲突导致openclaw --version显示版本但openclaw webui报command not foundWindows上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/openclawAlpine 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、编译TypeScriptM2 Mac耗时3分17秒。所以我的建议是新手首装用install.sh或install.ps1走npm5分钟跑通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——你必须先判断自己处于哪个矛盾象限。下面这张表帮你快速定位你的场景推荐方案关键命令验证方式Windows 10/11公司电脑禁用PowerShell脚本install-cli.shcurl -fsSL https://openclaw.ai/install-cli.sh | bashls ~/.openclaw/bin/openclaw*应存在.cmd文件macOS已装Homebrew且常用Terminalinstall.shcurl -fsSL https://openclaw.ai/install.sh | bashwhich openclaw返回/opt/homebrew/bin/openclawUbuntu服务器无root权限install-cli.sh --prefix $HOME/myopenclawcurl ... | bash -s -- --prefix $HOME/myopenclawecho $HOME/myopenclaw/bin必须在PATH中需要修改WebUI源码如增加自定义按钮install.sh --install-method gitcurl ... | bash -s -- --install-method gitls ~/openclaw/packages/webui/src/components/应存在React组件记住没有“最好”的方案只有“最适合你当前环境”的方案。接下来所有实操步骤都按此逻辑展开。3. 实操全流程从零开始每一步都附带现场验证指令3.1 Windows环境绕过PowerShell执行策略的终极解法Windows用户搜索量占全网67%但也是报错最集中的平台。核心痛点就两个npm.ps1报错和openclaw not recognized。别急着百度“怎么解除执行策略”那是在给系统埋雷。我们用官方脚本自带的逃生通道第一步确认PowerShell版本打开PowerShell不是CMD右键开始菜单→Windows PowerShell输入$PSVersionTable.PSVersion必须≥5.1Win10默认满足。若显示4.0说明你还在用旧版PowerShell升级到PowerShell 7https://github.com/PowerShell/PowerShell/releases。第二步用iwr替代curl规避网络代理干扰国内用户常因网络问题导致curl超时。官方脚本已适配iwrInvoke-WebRequestiwr -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安装的Nodev22.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 node24Homebrew的Node 24包尚未进入稳定通道。正确姿势curl -fsSL https://openclaw.ai/install.sh | bash脚本会自动检测若Node 24.x通过brew install node24若可用或brew tap homebrew/core brew install node24安装若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 ~/.zshrcM1/M2芯片用~/.zshrcIntel芯片可能用~/.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/DebianIDubuntu或debian用aptCentOS/RHELIDcentos或rhel用dnf或yumAlpineIDalpine用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-globalwhich 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并指定hostopenclaw webui --host 0.0.0.0 --port 8080--host 0.0.0.0表示监听所有网络接口--port 8080避开常见拦截端口。启动后终端会显示WebUI available at http://0.0.0.0:8080第二步获取本机局域网IPWindowsipconfig | findstr IPv4找无线局域网适配器 WLAN下的IPv4地址macOSifconfig | grep inet | grep -v 127.0.0.1找en0或en1下的地址Linuxhostname -I。第三步在其他设备访问手机浏览器输入http://192.168.x.x:8080将x.x替换为你的IP。若打不开检查防火墙Windows Defender防火墙→高级设置→入站规则→启用Node.js相关规则WSL2需在Windows中执行netsh interface portproxy add v4tov4 listenport8080 listenaddress0.0.0.0 connectport8080 connectaddress127.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用ReactTypeScript开发构建后生成静态文件后端API由packages/cli/src/commands/webui.ts启动的Express服务提供/api/skills、/api/gateway等REST接口技能执行引擎packages/runtime中的SkillRunner类负责加载.ts技能文件、注入工具、执行沙箱环境。启动openclaw webui时CLI会启动Express服务默认3000端口将packages/webui/dist作为静态资源目录在内存中初始化SkillRegistry扫描~/.openclaw/skills目录下的所有.ts文件。这意味着你修改packages/webui/src下的任何代码必须重新执行pnpm build才能生效。而修改~/.openclaw/skills/hello-world.ts保存后WebUI会自动热重载——这是官方刻意设计的开发体验分层。4.2 技能Skill的本质一个TypeScript函数 元数据声明创建一个最简技能只需三步1. 创建文件~/.openclaw/skills/greet.tsimport { 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必须导出greetmath-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}appidYOUR_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 错误代码速查表报错信息根本原因一键修复命令npm : 无法加载文件 ... npm.ps1PowerShell执行策略禁止脚本Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Forceopenclaw: command not foundPATH未包含openclaw所在目录echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrcError: Cannot find module typescriptNode版本与OpenClaw不兼容用install.sh重装确保Node≥24.xopenclaw webui: command not foundCLI未正确安装或PATH错位npm list -g openclaw-cli若为空则重装WebSocket connection failedWebUI端口被占用或防火墙拦截lsof -i :3000查进程kill -9 PID或换端口--port 8080Failed to load skill: SyntaxError技能TS文件有语法错误cd ~/.openclaw/skills tsc --noEmit greet.ts验证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 start5.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私有仓库配置Actionsname: Deploy OpenClaw Skills on: push: branches: [main] paths: [skills/**] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - 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——这比读文档快十倍。真正的工程师永远在动手前先看清楚机器要做什么。
