不吃章鱼烧最近两天我身边不下五个人拿着OpenClaw的安装文档来问我，说官网教程明明写得很清楚，但自己照着操作就是装不上，要么卡在PowerShell报错，要么装完了一运行又提示缺这缺那。我把聊天记录翻了一下，发现大家的问题其实高度集中：环境没提前检查、安装方式选错、配置阶段漏掉了关键步骤。所以干脆把OpenClaw全平台安装这件事一次性讲透，从Windows到macOS到Linux，从本机到Docker再到云端VPS，一套流程全部覆盖，顺便把我踩过的坑也一并写出来。
这份教程适合这样的人：第一次接触OpenClaw、之前只用过别人配置好的环境、或者在不同设备之间反复横跳想把运行环境统一起来的人。阅读全文大概需要十分钟，你得到的是一份可以直接照着敲命令的完整参考。
1. 装之前必须明白的几件事
1.1 OpenClaw 的核心定位
OpenClaw是一款开源的AI代理运行时，你往里面接一个模型，再给它一套工具权限，它就变成了一个能自主执行任务的"数字员工"。和简单调用API不同，OpenClaw把对话、工具调用、文件操作、命令执行这些能力包装成了标准化的运行时环境，你可以像管理容器一样管理它的生命周期。
安装OpenClaw这件事本身不复杂，复杂的是理解它的运行逻辑。我第一次接触的时候，以为它跟普通命令行工具一样，装完就能直接用，结果装完之后傻眼了——openclaw命令找不到，配置目录也不知道在哪，更别提接模型了。后来我才明白，OpenClaw的安装过程分为三层：核心程序层、配置管理层、运行时依赖层。核心程序是那个可执行文件，配置管理是它自动生成的~/.openclaw目录，运行时依赖则是它启动网关时需要的各种组件。
这里有一个关键认知：OpenClaw在Windows、macOS、Linux上的安装方式各不相同，但装完之后的目录结构和配置逻辑是统一的。也就是说，你在Windows上学到的排错思路，换到Linux服务器上依然适用。这也是为什么一份全平台教程比十份单平台教程更有价值——你只要理解一次配置模型，所有平台的问题都能跨平台迁移。
1.2 先选后端模型，再谈安装
安装之前先想清楚一个问题：你打算用哪个模型？这个问题直接决定你后面要准备哪些环境变量、要不要装额外的组件。
OpenClaw本身不内置大模型，它只是一个"壳"，你要往里接一个"大脑"。常见的接入方式有三类：闭源API（如OpenAI、Claude），开源模型的云服务（如通义千问），以及本地私有化部署（如Ollama）。如果你的模型是通过API调用的，OpenClaw安装时不需要额外装任何重组件，只要网络能访问对应服务就行；如果你打算接本地模型，那就要提前装好Ollama，并且确保显存和内存足够。
我建议新手从API方式开始。原因很简单：API方式的问题面更小，网络通了、Key填对了，基本就能跑起来。本地模型一旦出问题，你很难分清是OpenClaw的问题、Ollama的问题，还是模型本身的问题。等你用API方式跑通了整个流程，再切换到本地模型，排错思路会清晰很多。
1.3 Stable 与 Dev 版本怎么选
OpenClaw的更新机制跟很多开源项目类似，有stable（稳定版）和dev（开发版）两个通道。安装的时候默认进stable，但网上很多教程会让你用openclaw update --channel dev切到开发通道，原因是dev版更新更频繁，新功能更早暴露。
我的建议是：日常使用用stable，尝鲜用dev，别在生产环境使用dev。有一次我手痒切到dev通道，结果第二天起来发现网关一直显示"启动中"，查日志发现是某个依赖版本和系统库冲突。切回stable重新安装，十分钟解决了问题。dev通道的每一次更新都可能引入未充分测试的变化，它适合用来给项目提issue、反馈bug，不适合作为每天依赖的工作环境。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装前的环境检查
2.1 Node.js 环境准备
OpenClaw的核心运行时基于Node.js，所以装OpenClaw之前，第一件事就是确认Node.js版本。我遇到过不少安装失败的案例，追根溯源都是Node版本太老，OpenClaw的安装脚本在旧版本上无法正常执行。
Windows和macOS用户直接到Node.js官网下载LTS版本即可，Linux用户可以通过包管理器安装，也可以使用nvm来管理版本。装完之后在终端里执行：
bash复制node -v
npm -v
如果两个命令都能正常输出版本号，说明Node环境没问题。需要特别注意的是，Node版本不需要追新，LTS版本就够用，OpenClaw官方文档里标注了最低支持版本，一般低于这个版本才会报错。
2.2 终端与安装目录规划
OpenClaw的安装过程中，很大一部分操作需要通过命令行完成。Windows用户我强烈建议用PowerShell 7或Windows Terminal，别用老旧的cmd——不是不能用，而是cmd对UTF-8编码的支持较差，安装脚本输出中文乱码的时候，你根本分不清是警告还是报错。
安装目录的规划也是一门学问。OpenClaw默认会在你的用户主目录下创建.openclaw文件夹，里面存放配置、日志和workspace工作区。这个路径Windows下通常是C:\Users\你的用户名\.openclaw，macOS和Linux下是/Users/你的用户名/.openclaw或/root/.openclaw。
有人问能不能指定目录安装，当然可以，但我建议新手用默认目录。原因一是默认目录的权限模型经过充分测试，不容易出现权限问题；原因二是很多第三方工具和脚本默认读取这个路径，你改了目录就要处处改配置。等你对OpenClaw足够熟悉了，再按照自己的习惯自定义目录不迟。
2.3 网络环境的坑
OpenClaw的安装脚本、依赖包、模型API调用都依赖网络。国内用户安装时最常见的坑就是npm源或者某些下载地址访问不稳定。
处理方案有两种。第一种是给npm换源，把默认源指向国内镜像；第二种是设置OpenClaw的环境变量让它走代理。我的建议是先把npm源换掉，因为这只是几分钟的事，能解决大部分下载超时问题。至于代理设置，需要根据你实际网络环境来操作，不同场景差别很大，这里不展开。
注意：如果安装过程中长时间卡在下载阶段，先检查网络连通性，不要急着重装。可以换一个网络环境再试，有时就是单纯的网络波动导致安装中断。
3. Windows 平台安装
3.1 PowerShell 一键安装
Windows下最简单的安装方式是通过PowerShell执行官方安装脚本。打开PowerShell（建议以管理员身份），执行：
powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
iwr -useb https://openclaw.ai/install.ps1 | iex
第一行命令用来解除PowerShell对脚本执行的限制，第二行从官网拉取安装脚本并执行。这个过程会自动下载核心程序、创建.openclaw配置目录、写入环境变量。
装完之后验证是否成功：
powershell复制openclaw --version
如果输出版本号，说明安装成功。如果提示无法识别openclaw命令，不要慌，看3.3节。
3.2 便携包安装
有些Windows用户不想直接改系统环境变量，或者电脑权限管控比较严格，这种情况可以用便携包版本。OpenClaw官方提供了Windows的zip便携包，解压到任意目录就能使用，比如D:\OpenClaw\。
便携包的好处是不影响系统环境，缺点是每次启动前要手动设置环境变量，或者直接用完整路径调用。我是这样用的：先把便携包解压到固定目录，然后给openclaw.exe创建一个快捷方式，需要用的时候打开终端进入该目录再执行命令。
便携包有一个细节需要注意：程序首次运行时会自动在用户目录下创建.openclaw配置文件夹，这个文件夹和安装版的路径完全一致。如果你之前用过安装版，配置文件夹里已经有内容，便携包会自动读取这些配置，不用担心数据丢失。
3.3 常见的 cmdlet 报错与解决
Windows平台最常见的报错就是你运行openclaw时收到一条：
code复制OpenClaw : 无法将“openclaw”项识别为 cmdlet、函数、脚本文件或可运行程序的名
这句话的意思是系统找不到openclaw这个命令。出现这个报错的原因通常有三类：
第一类，安装脚本执行过程中网络超时导致环境变量没有写入成功。解决办法是检查环境变量里有没有OpenClaw的安装路径，没有的话手动添加。
第二类，安装路径可能被安全软件拦截了。某些安全软件会阻止安装脚本修改环境变量，或者隔离核心程序文件。解决办法是把OpenClaw的安装目录加入白名单，然后重新安装一遍。
第三类，如果你用的是便携包，但没有把解压目录加入PATH环境变量。解决办法是在PowerShell中执行：
powershell复制$env:Path += ";D:\OpenClaw"
这是临时生效的，重启终端就失效了。要永久生效，需要通过系统属性里的"环境变量"设置，把路径加到系统PATH里。
4. macOS 与 Linux 安装
4.1 macOS 安装与权限问题
macOS用户安装OpenClaw，最稳妥的方式是通过Homebrew。如果你还没装Homebrew，先装Homebrew，这是macOS生态的包管理基石。
终端执行：
bash复制brew install openclaw
这里有一个macOS特有的坑：如果之前没有安装过Xcode Command Line Tools，安装Homebrew时系统会弹窗提示安装，这个等待过程可能长达十几分钟。如果你在安装OpenClaw时碰到奇怪的编译错误，先检查Xcode Command Line Tools是否完整：
bash复制xcode-select --install
macOS还会遇到"无法打开，因为无法验证开发者身份"的提示。这是因为OpenClaw的安装文件没有经过Apple官方公证，系统默认拦截。解决办法是在"系统设置-隐私与安全性"中允许来自未知开发者，或者右键点击应用选择"打开"。这种安全机制每年都会劝退一堆新手，实际用起来没什么风险，放到白名单里即可。
4.2 Linux 安装
Linux安装OpenClaw的通用方式是一行脚本：
bash复制curl -fsSL https://openclaw.ai/install.sh | bash
这个方式对Ubuntu、Debian、CentOS大体通用，脚本会自动检测系统架构，下载对应的二进制包。装完同样执行openclaw --version验证。
如果你用的是Arch Linux，可以直接通过AUR安装，体验会更好，因为AUR里的安装包会跟随上游仓库自动更新。其他发行版用官方脚本即可。
Linux上还有一个隐藏坑：glibc版本太旧。OpenClaw的新版本可能在编译时使用了较新版本的glibc，旧系统上运行时会出现段错误或者"version GLIBC_2.34 not found"之类的报错。遇到这种情况，要么升级系统基础库，要么用Docker方式运行（见5.1节）。
4.3 服务器上 root 用户目录的权限坑
在云服务器上以root用户安装OpenClaw，通常会看到一条警告，说/root/.openclaw/exec-approvals.json已经存在，询问是否覆盖。这个文件记录了你批准过的所有待执行命令，默认权限模型下，OpenClaw每次执行敏感命令前都会询问你。
作为一个常驻后台运行的工具，反复确认命令会非常烦人。很多用户的解法是修改配置文件跳过确认环节。我不建议这么干，特别是服务器上。服务器上跑的东西可能是无人值守的，一旦跳过确认，恶意命令或误操作就没有任何拦截机制，风险很大。
更好的做法是让OpenClaw只运行在一个独立用户下，不要直接使用root。可以新建一个用户：
bash复制useradd -m claw
su - claw
curl -fsSL https://openclaw.ai/install.sh | bash
这样做的好处是权限边界清晰，就算OpenClaw被诱导执行了危险命令，破坏范围也仅限于这个普通用户的家目录，不会直接炸穿整个服务器。
5. Docker 与云端部署
5.1 Docker 部署
Docker是跨平台部署OpenClaw最省心的方式，特别是在Windows和Linux混用的团队里，一份docker-compose配置在所有机器上行为一致。用Docker还有一个额外好处：完全绕开前文提到的Node环境、glibc版本、权限模型等一堆问题。
官方镜像的启动命令：
bash复制docker run -d \
--name openclaw \
-v /path/to/.openclaw:/root/.openclaw \
-e OPENCLAW_MODEL=openai/gpt-4o \
-e OPENCLAW_API_KEY=sk-xxxx \
-p 18789:18789 \
openclaw/openclaw:stable
几个参数解释一下。-v把主机上的配置目录挂载到容器里，这样容器销毁重建后配置还在；-e用来传环境变量，API Key和模型名称都走这里；-p把容器内的18789端口映射到宿主机，这是OpenClaw网关的默认端口。
Docker方式有一个体验上的差异：容器里的OpenClaw执行Shell命令时，操作的是容器内部的文件系统，不是你宿主机的文件系统。如果你打算让OpenClaw管理本地文件，需要额外挂载对应目录：
bash复制-v /host/data:/data
这是一个很容易被忽略的地方。我在Docker里第一次跑OpenClaw时，让它去读取一个宿主机文件，结果它怎么也找不到，后来才想起需要把目录挂载进去。
Windows用户如果用Docker Desktop，还需要注意WSL2的内存限制。OpenClaw本身不占用太多内存，但如果你同时跑多个容器，或者宿主机内存本来就不大，需要手动调整WSL2的.wslconfig内存上限。
5.2 云端VPS部署与systemd
把OpenClaw部署到云端VPS，可以让你随时通过Web端或者其他设备远程调用能力。云服务器的选型上，入门级配置（1核2G）就够跑OpenClaw的基础功能，不过比较吃紧，建议2核4G起步，省得后面扩展时处处受限。
安装步骤跟Linux本机一致，但为了让它在SSH断开后依然保持运行，建议用systemd托管进程。先创建服务文件/etc/systemd/system/openclaw.service：
ini复制[Unit]
Description=OpenClaw Service
After=network.target
[Service]
User=claw
WorkingDirectory=/home/claw
ExecStart=/home/claw/.openclaw/bin/openclaw serve
Restart=always
RestartSec=10
Environment=OPENCLAW_MODEL=openai/gpt-4o
Environment=OPENCLAW_API_KEY=sk-xxxx
[Install]
WantedBy=multi-user.target
然后执行：
bash复制systemctl daemon-reload
systemctl enable --now openclaw
这里有几个细节。Restart=always让服务崩溃后自动拉起，RestartSec=10是重启间隔，避免频繁崩溃时无限重启。环境变量直接写在服务文件里，比写在启动脚本里更清晰。如果你不想用systemd，也可以用Screen或Tmux开一个常驻会话，但远不如systemd可靠，服务器重启后你还要手动恢复会话。
5.3 迁移和备份
OpenClaw的完整状态就在那一个.openclaw目录里，包含配置文件、workspace工作区文件、exec-approvals权限记录。这意味着备份和迁移极其简单：打包这个目录，传到新机器解压，然后重新安装OpenClaw程序本体。
我多次在Windows和Linux之间迁移，经验是先看目录里一个runtime-metadata.json文件，这里记录了当前运行的版本和通道信息。迁移过去之前，先用openclaw update把版本对齐，再拷配置，可以减少很多奇怪的兼容性问题。
有一点要提醒：如果配置里存了API Key或者其他敏感信息，迁移后要及时检查新机器上这些配置是否还在，并且不要把这个目录直接放进Git仓库。
6. 初始化配置与模型接入
6.1 首次运行与网关启动
安装完成后首次运行，执行：
bash复制openclaw
正常情况下会看到控制台输出一段初始化日志，然后提示输入模型提供商信息。这个过程会自动配置本地网关，网关的作用是让OpenClaw和模型服务之间建立持久连接，消息不再是一次性HTTP请求，而是通过gateway长时间保持会话。
但我发现很多Windows用户卡在"网关启动中"这一步。如果你在Windows上等待超过几分钟还没看到提示信息，大概率是防火墙拦截了网关的本地端口。解决办法：在Windows防火墙入站规则中放行OpenClaw程序，或者放行18789端口。修改完重新运行openclaw serve，网关很快就能起来。
6.2 不同模型提供商的配置方法
OpenClaw支持通过环境变量或配置文件指定模型。方式一，在启动时用环境变量指定：
bash复制export OPENCLAW_MODEL="openai/gpt-4o"
export OPENCLAW_API_KEY="sk-xxxx"
openclaw
方式二，在.openclaw配置文件里维护多套模型配置，运行时通过指令切换。我倾向第二种，因为实际工作中可能同时用到多个模型——比如日常问答用千问免费token，写代码用Claude，本地实验用Ollama跑小模型。
需要说明的是，OpenClaw模型配置遵循的是"provider/model-name"的格式。使用Ollama本地模型的时候，只要Ollama服务跑着，OpenClaw配置里把模型地址指向http://localhost:11434，就能把本地模型接入进来。第一次跑通这个链路时，你会明显感受到私有化部署和云端API之间的体验差异——本地模型的延迟更低，但效果上限受你硬件制约。
6.3 Workspace 与 Exec Approvals 的说明
OpenClaw的workspace是它操作文件系统的活动范围，默认在.openclaw/workspace下。你可以把它理解成给AI划定的一间办公室——AI可以在里面创建、修改、删除文件，但不能越界。
这个设计很有价值。你没有限制的时候，AI可能为了执行一条命令就去翻你的系统文件；有了workspace边界，它的操作范围被圈定，出问题的概率大大降低。如果你需要让OpenClaw访问其他目录，可以在配置中挂载额外的可访问路径。
另一个关键配置是exec-approvals。前文提到过，OpenClaw要执行Shell命令时，会检查命令是否在批准列表里。没有批准的指令默认会弹出确认提示，让你选择允许还是拒绝。这个机制看着繁琐，实际是保护你的最后一道闸门。
我见过有些教程建议把确认机制关闭，理由是"AI执行任务不应该每次都打断"。对于纯个人娱乐环境，这么干问题不大；但如果你用OpenClaw处理工作内容，我强烈建议保留确认机制。毕竟AI偶尔会提出一些匪夷所思的命令，有确认提示兜底，最多损失几秒钟时间，但可以避免一次重大事故。
7. 常见问题排查与速查
7.1 故障速查表
我在多个平台反复安装OpenClaw，把常见问题整理成了一张速查表，你遇到问题时可以按图索骥：
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
| 安装脚本执行失败 | 网络不通或下载超时 | 更换网络/换npm源后重试 |
| openclaw命令不存在 | 环境变量未配置 | 手动添加安装目录到PATH |
| 网关一直启动中 | 防火墙拦截本地端口 | 放行程序或18789端口 |
| 提示无法验证开发者 | macOS安全策略 | 允许未知开发者运行 |
| 容器里找不到宿主机文件 | 没有挂载数据卷 | 用-v参数挂载对应目录 |
| 服务频繁崩溃 | systemd配置错误 | 检查日志journalctl -u openclaw |
| 提示exec-approvals.json已存在 | 重复初始化 | 按提示选择覆盖或保留 |
这张表不是万能的，但覆盖了90%的新手问题。记住一个排查原则：先看配置文件是否生成，再看日志输出。
7.2 三个我踩过的坑
第一个坑：在Windows上装完执行openclaw，一直提示无法识别命令，后来发现是安全问题，安装脚本已经执行成功，但杀毒软件把程序文件隔离了。处理方式是把安装目录加入信任区，重新安装。
第二个坑：在Linux服务器上用root直接跑OpenClaw，配置文件生成在/root/.openclaw，后来想迁移到普通用户，发现权限问题一大堆。再后来学乖了，新建了一个专用账号来跑，世界清净了。
第三个坑：一开始贪新鲜切到dev通道，结果某次更新后启动报错，查了半天发现是某个依赖版本和系统不兼容。浪费了整整一个下午之后，我现在的原则是：工作环境永远stable，实在想尝鲜，用Docker起一个测试实例随便折腾。
7.3 用系统命令诊断运行状态
很多人在OpenClaw运行异常时不知道如何入手。其实最简单的诊断方式就是看进程和日志。
bash复制ps aux | grep -i openclaw
这条命令在Linux和macOS上通用，可以快速确认OpenClaw进程是否存在、占用了多少资源。如果进程不存在，说明服务没起来；如果存在但网页端连不上，问题大概率出在端口监听或防火墙。
日志方面，OpenClaw运行时会在.openclaw/logs/目录下按日期写入日志文件。遇到报错时不要只盯着控制台，打开当天的日志文件看完整个堆栈信息再下结论。
8. 几个容易被忽略但很实用的配置
8.1 Skill 机制与插件扩展
OpenClaw从2.0版本开始引入了Skill机制，简单说就是给AI定义一组动作模板。你可以在.openclaw/skills/目录下放置自定义技能，也可以通过ClawHub安装别人分享的技能包。
这点和OpenClaw的姊妹产品ClawHub有明确分工：ClawHub是技能的社区仓库，OpenClaw是运行技能的运行时。你用openclaw skill install命令可以从ClawHub拉取技能，不用手动下载解压。
实际开发中，Skill机制和飞书、微信这类IM工具的接入配置往往是搭配使用的——你可以写一个"自动向飞书群发日报"的技能，然后让OpenClaw每天定时执行。这个玩法的上限很高，但依赖你对Skill配置的理解深度，初学阶段先装一个别人的技能跑通流程，再自己动手写。
8.2 移动端与远程访问
如果你不想天天守在电脑前，可以使用OpenClaw Desktop配合云端的OpenClaw服务端来使用，界面体验跟本地运行差不多，但实际计算都在云端执行。
这里有个体验建议：远程访问时，网关端口记得只对可信IP开放，或者走标准身份认证流程。直接本地端口裸奔到公网，很容易被扫描器盯上。
我自己现在的架构是：云端VPS跑一个systemd托管的OpenClaw服务，本地电脑和手机通过客户端连接同一个网关，模型统一走API，数据都在云端。这套方案的好处是，不管我在哪台设备上，打开客户端都是同一个对话上下文，适合长期维护同一个人工智能工作流。
8.3 与项目管理工具的结合
OpenClaw嵌入日常项目管理流程，是它除了编程辅助外最实用的场景之一。你可以让OpenClaw定时读取一个需求文档目录，提取待办事项更新到项目管理软件中；也可以让它根据日报内容自动生成周报；甚至可以让它监听某个文件夹，新文件出现就自动触发处理流程。
这类自动化场景的关键，还是理解workspace的边界和exec-approvals的确认机制。设计自动化任务时，尽量把OpenClaw的读写路径限制在一个特定目录内，不要把所有目录都开放给它。范围越小，出意外的可能性越低。
最后聊两句我自己的使用感受
OpenClaw目前的安装体验已经比早期版本好了太多，早期我需要手动拉源码、编译依赖、配置环境变量，路径对不上就要折腾一下午。现在有了一键脚本和官方镜像，跨平台部署的复杂度大幅下降。但无论安装工具怎么进化，理解它的目录结构、配置模型和权限机制，依然是排解一切问题的基础。
如果你在安装或配置过程中遇到我正文里没写到的报错，我的建议是先把完整报错信息贴到搜索引擎里——很多人遇到问题第一反应是重装，但重装并不能解决配置层面的错误。多花五分钟看看日志，往往比你重装三遍更高效。
最后还有一个小技巧：装好之后不要着急接复杂模型，先用默认配置跑一次最简单的对话，确认链路完全通了，再逐步加模型、加技能、加自动化。基础不牢的话，功能堆得越多，排查问题就越头疼。按这个顺序来，你会在OpenClaw上少走很多弯路。