1. 安装前的思路与准备
我第一次看到 openclaw 这个项目的时候，第一反应是：这名字有点意思，像是某种“爪”系工具。深入看了一下才发现，它并不是什么花哨的玩具，而是一个定位在本地自动化和私密工作流管理上的开源工具，核心思路是通过一套统一的命令接口，把日常那些重复、繁琐、需要跨应用协作的操作，整合成可复用的任务流。简单说，如果你的工作里充满了“把这里的数据整理好，发到那里去”“定时检查某个状态，然后按条件触发动作”这类活，openclaw 能帮你省下大量手动操作的时间。
更重要的是，openclaw 默认是本地运行，数据不经过第三方服务，这对注重隐私的场景非常友好。而且它的安装方式很灵活，不同平台都有对应的安装包，也支持从源码编译。这篇教程我会带你完整走一遍安装流程，覆盖 Windows、macOS、Linux 三种主流平台，以及源码编译方式，并配上过程中会遇到的各种坑的排查方法。无论你是第一次接触这类工具的小白，还是已经熟练使用命令行想快速部署的老手，都能对照着操作。
在动手安装之前，我想先说清楚一个原则：安装软件和配置环境，其实很像组装一台新电脑——最忌讳的就是不看说明书，东一把西一把地装，最后出了问题根本不知道是哪里错了。所以我们在正式操作前，先花几分钟明确几个关键点，后面会少走很多弯路。
1.1 openclaw 到底是什么，能解决什么问题
openclaw 本质上是一个“任务编排与自动执行框架”。你可以把它理解成一个骨架：它本身不提供太多具体的业务功能，但它提供了一套标准的接口和运行环境，让你能把各种脚本、命令行工具、HTTP 请求、文件操作等元素串联起来，形成一个有逻辑、可复用的自动化流程。
举个例子，很多人的日常工作里会有这样一条固定流程：每天早上到公司后，首先打开某个管理后台，查看昨天生成的报表，把异常数据记录下来，然后把结果整理成消息发到团队群。这个流程如果靠手动操作，通常需要打开两三个页面、复制粘贴好几轮，耗时十分钟左右。而 openclaw 可以把这些步骤全部编排进同一个任务文件里，执行触发器可以根据时间、文件变化或外部请求来设定。执行时你只需要一个命令，剩下的它自己跑完。
所以它解决的核心问题不是某个单一功能的自动化，而是“跨步骤、跨工具、可重复”的自动化。这也决定了它的安装不能是简单的下一步、下一步，你需要稍微了解一下它的运行环境和依赖关系，才能保证后续使用顺畅。
1.2 安装模式的选型：包管理器、二进制还是源码编译
openclaw 的安装方式大致有三类：包管理器安装、预编译二进制包安装、源码编译安装。这三类方式没有绝对的好坏，关键看你当前的环境条件和使用习惯。
- 包管理器安装：这种方式适合大多数普通用户。优点是命令短、自动下载依赖、升级方便，缺点是包管理器里收录的版本可能不是最新，如果你需要紧跟上游的新特性，往往要等一段时间。
- 预编译二进制包安装：适合想要最新版本、不想管依赖的用户。下载解压即可用，但你需要自己关注版本更新，手动替换旧文件。
- 源码编译安装：适合需要修改源码、二次开发，或者当前平台没有现成包的情况。这种方式最灵活，但对环境要求最高，编译过程中可能出现各种依赖缺失的问题。
以我自己的经验来说，第一次接触一个新工具，或者只是想评估它能不能满足需求，优先用包管理器安装或预编译二进制包。这两种方式最快，能迅速把工具跑起来，验证功能和体验。等到你确认这个工具值得长期使用，并且有一定的定制需求时，再考虑源码编译。不要一上来就挑战编译安装，那样很容易在环境配置阶段就消耗掉你所有耐心。
1.3 环境检测与版本兼容性判断
在开始安装之前，有一个非常重要的步骤：确认你当前的操作系统版本、CPU架构，以及已经安装好的基础运行环境。很多安装失败的问题，根本原因不是工具本身有问题，而是环境不匹配。
openclaw 在不同版本上对系统环境的要求略有差异，但总体上有几个共通的检测项：
- 操作系统版本。openclaw 的预编译包通常对系统版本有最低要求，比如较新版本会要求 Windows 10 以上、macOS 11 以上、Ubuntu 20.04 以上。如果你的系统版本过老，安装时会直接提示不支持。
- CPU 架构。现在主流设备有 x86_64、arm64 两种架构，部分 ARM 设备还需要区分是 32 位还是 64 位。下载安装包时如果不注意架构，后果通常是“Permission denied”或“Exec format error”。我见过不少人卡在这一步，但大家往往第一时间想不到是架构问题。
- 基础依赖。openclaw 的核心运行时主要依赖系统自带的工具链和库。在 Linux 上，最常见的依赖是 build-essential、curl、git；在 macOS 上，如果没有安装命令行工具，会因为缺少编译器而报错。这些依赖不检查好，后面很容易出问题。
在正式开始安装前，请先执行下面的命令，确认你的系统信息。
uname -a这条命令在 macOS 和 Linux 上都会显示内核版本、CPU 架构等信息。在 Windows 上，可以在 PowerShell 里用下面的命令：
$PSVersionTable这个命令显示 PowerShell 版本，再看“OS”和“Platform”字段，就能确认系统版本和架构。确认后，再去官网下载对应版本，能避开一半以上的安装问题。
2. 核心安装流程详解
有了前面的准备和思路，下面进入正式安装环节。我会按照 Windows、macOS、Linux 的常见安装顺序来写，每个平台都给出可以直接复制执行的命令，并对关键步骤做解释。你可以根据自己的系统直接跳到对应小节。
2.1 Windows 平台安装 openclaw 的完整步骤
Windows 平台推荐使用预编译二进制包或 Windows 包管理器安装。先说我日常用得最多的方式。
2.1.1 使用包管理器安装
如果你已经安装了 Windows 包管理器，那么安装 openclaw 非常简单。在 PowerShell 中执行：
winget install openclaw这条命令会自动从官方源拉取安装包并安装。安装完成后，可以通过下面的命令验证：
openclaw --version如果看到版本号输出，说明安装成功。
不过这里有一个细节：winget 安装的版本可能不是最新，如果你想尝鲜新功能，也可以从官网下载最新的二进制包。下载后，你会得到一个 zip 压缩包，里面只有一个 exe 可执行文件和若干辅助文件。
2.1.2 手动安装二进制包
手动安装的核心只有三步：解压、加入环境变量、验证。
下载完成后，先找到这个文件夹。比如下载到了D:\claw-download。然后解压到目标目录。我个人建议统一放到一个专门的工具目录，比如D:\tools\openclaw，方便后期维护。
Expand-Archive -Path D:\claw-download\openclaw-win-x64.zip -DestinationPath D:\tools\openclaw解压之后，进入目录，把当前目录临时加入 PATH，验证是否能运行：
cd D:\tools\openclaw .\openclaw.exe --version这里要注意：在 PowerShell 里，运行当前目录的可执行文件必须加上.\，这是 Windows 下的一个安全机制，防止直接执行同目录下的恶意程序。
验证成功后，需要把可执行文件的目录加入系统环境变量，否则以后每次使用都要切换到安装目录，非常麻烦。这一步的操作为：按Win + R，输入sysdm.cpl，回车后在“高级”标签页中点击“环境变量”。在“系统变量”中找到Path，编辑并新增一行，填入D:\tools\openclaw。完成后重新打开 PowerShell，再次运行openclaw --version，无论你在哪个目录下都能正常调用，说明环境变量配置生效。
2.2 macOS 平台安装 openclaw 的完整步骤
macOS 上我推荐先检查是否安装了命令行工具，然后直接用 Homebrew 安装，这样可以自动处理大部分动态库依赖。
2.2.1 命令行工具的检查
在安装 openclaw 前，打开终端，执行：
xcode-select -p如果输出/Library/Developer/CommandLineTools，说明命令行工具已安装。如果提示找不到工具，就执行：
xcode-select --install系统会弹窗引导安装。千万别跳过这一步，否则后面的编译或安装过程会报clang: error: no input files或找不到头文件等信息。
2.2.2 Homebrew 安装方式
命令行工具就绪后，安装 Homebrew（如果还没装）。在终端里执行：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"这里说明一下，Homebrew 会安装到/opt/homebrew（Apple Silicon）或/usr/local（Intel）。安装完成后，执行：
brew install openclaw这个命令会自动下载依赖包、配置路径。整个过程可能需要几分钟，取决于网络状况。安装完成后，验证：
openclaw --version如果没问题，macOS 的安装就算完成。
2.2.3 Apple Silicon 用户需要注意的架构问题
我身边有不少用 M 系列芯片的朋友，第一步就栽在架构问题上。如果你的机器是 Apple Silicon，从官网下载二进制包时，不要选darwin-amd64，而要选darwin-arm64。如果选错，终端会报killed: 9或cannot execute binary file。
另外，macOS 系统默认的安全策略比较严格，如果你手动下载并打开一个未签名或未公证的应用，会提示“无法验证开发者”。遇到这个情况，不用担心，你可以右键点击应用图标，选择“打开”，然后在弹窗里确认打开。或者用命令行去除隔离属性：
xattr -d com.apple.quarantine /path/to/openclaw这个命令的含义是移除文件的“隔离”扩展属性。但要注意，仅在你确认下载来源可信的情况下使用，否则不建议随意绕过系统安全检查。
2.3 Linux 平台安装 openclaw 的完整步骤
Linux 平台的安装方式最灵活，也最容易出错。不同发行版的包管理器差异很大，我以 Ubuntu/Debian 系和 CentOS/RHEL/Fedora 系为例分别说明。
2.3.1 Ubuntu / Debian 系安装
先更新软件源并升级已安装的软件包：
sudo apt update && sudo apt upgrade -y然后安装基础依赖：
sudo apt install -y curl git build-essential接下来，使用官方安装脚本安装：
curl -fsSL https://openclaw.example.com/install.sh | bash安装脚本会检测你的系统版本、架构，然后下载对应的二进制包到~/.openclaw/bin，并自动配置 PATH 环境变量。脚本执行完成后，需要重新加载 shell 配置：
source ~/.bashrc如果你是 zsh 用户，就执行：
source ~/.zshrc最后验证：
openclaw --version这里我想特别提醒：在 Linux 上有一种很常见的错误习惯，就是完全信任管道安装脚本，直接curl | bash。这种做法虽然方便，但如果脚本本身有误或者来源不可信，风险很高。建议先看看脚本内容再执行：
curl -fsSL https://openclaw.example.com/install.sh | less大略浏览一下脚本里做了什么，确认路径和命令没有明显问题后再执行。
2.3.2 CentOS / RHEL / Fedora 系安装
这些发行版的默认软件源里往往没有 openclaw，所以通常建议使用官方 rpm 仓库或直接下载二进制包。安装 rpm 包的方式是：
sudo yum install -y /path/to/openclaw.rpm如果你下载的是 tar.gz 压缩包，安装方式更轻量，解压并加入 PATH 即可：
tar -xzf openclaw-linux-x64.tar.gz -C ~/.local/ echo 'export PATH="$HOME/.local/openclaw:$PATH"' >> ~/.bashrc source ~/.bashrc使用~/.local目录的好处是，不需要 sudo 就能完成安装，而且不会污染系统目录。如果你需要让系统内所有用户都能使用，才建议放到/usr/local/bin下。
2.4 源码编译安装 openclaw
如果你需要对 openclaw 做二次开发，或者官方没有提供你所在平台的预编译包，那么源码编译就是必经之路。
2.4.1 拉取源码与准备编译环境
源码编译的第一步是把代码拉下来：
git clone https://github.com/openclaw-project/openclaw.git cd openclaw然后你需要确保编译工具链完整。在 Ubuntu 上，依赖主要是build-essential、cmake、pkg-config。除了之前已经安装的build-essential，还需要安装：
sudo apt install -y cmake pkg-configmacOS 上如果安装了命令行工具和 Homebrew，通常就够了。Windows 上源码编译比较繁琐，一般需要安装 Visual Studio 的 C++ 构建工具，并确保能访问 Windows SDK。
2.4.2 编译命令与常见参数
openclaw 使用 CMake 作为构建系统。编译过程通常是：
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release cmake --build build -j$(nproc)第一个命令是配置编译选项，-S .指定源码目录，-B build指定生成目录，-DCMAKE_BUILD_TYPE=Release编译发布版本。第二个命令是执行编译，-j$(nproc)表示用当前机器的所有 CPU 核心并行编译，能显著缩短时间。
编译完成后，生成的二进制文件在build目录下。你可以直接将build/openclaw复制到/usr/local/bin，也可以保留原路径，通过软链接方式加入环境变量：
ln -s $(pwd)/build/openclaw /usr/local/bin/openclaw编译过程中最常见的错误是缺少某个开发库的头文件，比如zlib.h、openssl/ssl.h。这类问题的通用解法是安装对应的 dev 包。以 Ubuntu 为例：
sudo apt install -y zlib1g-dev libssl-dev按照报错提示逐个补齐即可，不要试图强行跳过依赖检查。
3. 安装后的验证与初始化配置
安装完 openclaw 并不意味着能直接开始用，你还需要完成两项工作：验证运行环境是否正常，以及初始化基础配置。这一步做得仔细，能避免后续使用中很多稀奇古怪的报错。
3.1 验证命令工具是否正常
在终端里执行：
openclaw doctor这是我特别推荐的一条命令。它不是简单的版本号检查，而是会全面扫描当前系统的运行环境，包括依赖库是否存在、网络连通性是否正常、主配置目录是否可写、关键目录权限是否正确等。如果一切正常，会输出绿色的ok状态项；如果有问题，会给出具体的错误信息和建议修复方式。
除了doctor，再执行一次openclaw --version，确认版本号。这里有一个经验：如果输出里带有dev或preview字样，说明你安装的是开发版或预览版，这类版本功能新但稳定性可能稍差，适合尝鲜；生产使用尽量选择稳定版。
3.2 初始化用户配置目录
openclaw 的工作方式是基于配置文件来定义和执行任务的。第一次使用前，需要初始化一个用户配置目录，默认位置如下：
- Linux:
~/.config/openclaw - macOS:
~/Library/Application Support/openclaw - Windows:
%APPDATA%\openclaw
执行初始化命令：
openclaw init这个命令会自动创建默认配置目录，并生成一份基础配置文件。如果你打开这个文件，会发现里面有若干个区块，比如全局设置、日志级别、任务目录路径等。这里我建议初始化后先保持默认值，不要立刻修改，等实际跑通一个任务后，再根据需求逐步调整。
初始化完成后，可以看一下目录结构：
ls -la ~/.config/openclaw如果能看到配置文件，说明初始化成功。
3.3 配置一个最简单的测试任务
为了确认安装没有白装，我建议接着做一个最简单的冒烟测试。新建一个测试任务文件：
openclaw example --output /tmp/claw-first-test这个命令会生成一个演示用的任务示例，并执行它。执行完成后，去/tmp/claw-first-test目录下查看输出：
cat /tmp/claw-first-test/*如果能看到内容输出，恭喜你，openclaw 的核心安装和配置已经全部完成。这个测试不需要涉及具体业务，它只是为了验证工具是否能正常调度和执行任务。
3.4 配置日志与路径习惯
openclaw 本身会输出运行日志，默认日志级别是 info，保存在配置目录的logs子目录。我在使用中一般会把日志级别调整为 warn，因为生产环境里 info 级别的日志量太大，反而不容易发现关键错误。调整方法是编辑配置文件，把log_level字段改为：
log_level = "warn"还有一个值得养成的习惯：不要把任务文件散落在系统各处。在配置文件中指定一个专门的任务目录，比如：
task_dir = "/home/yourname/claw-tasks"以后所有任务文件统一放在这个目录，便于管理和备份。我自己会用 git 来管理这个目录，每次修改任务配置后都提交一次，这样万一改坏了还能回滚。
4. 常见问题与排查技巧实录
再完美的安装教程也不可能覆盖所有环境，这里我把实际使用中遇到过、以及帮别人排查过的典型问题汇总成速查表，按问题现象、原因和解决办法来写，方便你对照处理。
4.1 命令找不到的排查思路
如果你在终端里输入openclaw提示command not found，请按照下面的顺序依次排查：
- 启动一个新的终端窗口，或者执行
source ~/.bashrc/source ~/.zshrc。很多情况下，旧终端窗口的环境变量没有刷新，导致找不到刚安装的命令。 - 确认安装路径是否已加入 PATH。执行
echo $PATH，检查输出里是否包含 openclaw 的安装目录。 - 确认安装目录下是否存在可执行文件。在 Linux 上执行
ls -l ~/.openclaw/bin/openclaw，查看文件权限。如果权限位显示没有x，则执行chmod +x ~/.openclaw/bin/openclaw。
这里敲一下重点：Windows 系统上还存在一种特殊情况，装了新版，却还在运行旧版，因为旧版路径比新版路径在 PATH 里的顺序更靠前。解决办法是在PATH中把新版路径前移。
4.2 Permission denied 或 Exec format error
这类错误几乎都指向两个原因：架构不匹配或文件权限错误。
架构不匹配的报错信息通常是cannot execute binary file: Exec format error或killed: 9。第一步去官网确认你的 CPU 架构，不要想当然。特别是 Windows ARM 设备、macOS Apple Silicon 设备，下载时一定要选arm64版本。如果你手头有file命令，还可以直接检查一下可执行文件的架构：
file openclaw它会输出类似x86-64或arm64的信息，和系统的uname -m输出对照一下即可。
权限错误的报错信息通常是Permission denied。在 Linux/macOS 上，执行：
chmod +x /path/to/openclaw即可。如果把这个二进制文件放到了/usr/local/bin，还需确认文件所有者与当前用户一致，否则也要调整。
4.3 依赖缺失导致的启动失败
这类问题在源码编译或使用未打包完整版本时最常见。启动时报error while loading shared libraries: libxxx.so.1: cannot open shared object file，意思就是缺少某个动态链接库。解决办法是按系统安装对应运行时库。
在 Ubuntu 上，可以先尝试安装最基本的依赖：
sudo apt install -y libcurl4-openssl-dev libssl-dev libzstd-dev如果报错信息里提到了某个具体的库，比如libssl.so.3，你可以用包管理器搜索对应的包名：
apt search libssl然后安装缺少的那个版本即可。macOS 上如果提示缺少动态库，通常是因为 Homebrew 安装的依赖没有链接，可以执行：
brew install openssl zstd再重新运行openclaw试试。这类问题并不难解决，关键是不要慌，逐字读报错信息，它会明确告诉你缺的是什么。
4.4 配置文件无法写入或读取失败
如果你在启动或执行任务时看到类似permission denied while reading configuration的提示，原因通常是配置目录权限不对。在 Linux 上，检查一下配置目录的所有权和建议权限：
ls -la ~/.config/openclaw chmod -R u+rwX ~/.config/openclaw如果配置目录是 root 所有，而你用普通用户运行，就会无法写入。解决方法是更正目录所有者：
sudo chown -R $USER:$USER ~/.config/openclaw还有一个常见问题：有些用户把配置目录设置在云盘同步目录，比如 OneDrive 或 iCloud 下，导致文件被持续占用，偶尔出现读取失败。我给的建议是，不要将配置目录放在云同步目录，这类工具需要稳定的本地文件访问。
4.5 旧版本残留导致的行为异常
如果你从旧版本升级到新版本，有时候会发现命令行为不一致。这种情况多半是旧版本配置残留导致的。升级前最好备份一份配置目录，然后清空重来。
我个人的习惯是升级后先执行：
openclaw doctor让它自行检查配置版本和兼容性。如果检查结果提示配置版本过旧或有已废弃字段，再主动升级配置：
openclaw config migrate这条命令会把旧版配置转换为新版格式，并保留原有内容。如果转换失败，就只能手动参考新版的示例配置改写了。记住一个原则：任何工具升级前都要备份配置，这能让你在任何异常情况下都有一条退路。
4.6 网络受限环境下安装失败的应对
工作环境里常有内网或代理限制，导致安装脚本无法从远程仓库拉取文件。这种情况下，建议直接在一台能联网的机器上把安装包下载好，再用 U 盘或内网传输工具拷贝到目标机器。
离线安装的具体操作是：拷贝整个安装目录（或解压后的二进制包）到目标机器，设置好 PATH，然后执行openclaw init初始化。openclaw 的离线安装包是自包含的，不需要额外的联网依赖，所以这种方式非常可靠。
如果你是源码编译且环境受限，那就要提前把源码包和所有依赖源码都准备好，必要时在编译命令中指定本地依赖路径。这个操作成本高，非必要不推荐。
5. 安装体验总结与长期维护建议
到这一步，openclaw 应该已经在你的机器上跑起来了。我个人在实际安装和使用中的体会是，openclaw 安装过程本身并不复杂，但真正影响体验的，往往是你对环境的掌握程度和对待配置的态度。我见过太多人抱怨安装失败，追根究底，多数是没看系统提示、没对齐架构、跳过了依赖安装，或者改配置时随意引入格式错误。只要你在安装前花三分钟做环境检测，安装后花两分钟做冒烟测试，这个工具就能稳定运行很久。
最后再分享一个小技巧：openclaw 升级通常不会太频繁，但每次升级后都值得花点时间跑一遍示例任务，确认核心功能没有受影响。我自己会维护一个小型的“回归任务集”，里面包含几个不同类别的任务模板，每次升级后依次执行一遍。这样既验证了安装，也为后续使用积累了一份可作为起点的脚本素材。如果你已经成功安装，建议现在就顺手建一个自己的任务目录，从一个最简单的定时任务开始，让它帮你跑起来。
