企业官网建设流程全解析

如果你在终端里执行openclaw update，日志里突然冒出一行Skipped: this OpenClaw install isn't a git checkout, and the package manager...，先别慌，这大概率不是更新失败。我第一次看到这行字的时候，也愣了几秒，以为更新半路被什么东西拦住了。后来翻了安装目录和更新逻辑，才明白这其实是一个“提示”而不是“报错”：它发现当前安装目录没有.git，不是通过git clone装的源码版，于是跳过了 git 更新这条路径，准备把更新交给包管理器去做。

这篇东西写给两类人：一类是刚部署 OpenClaw，看到 Skipped 提示不知道要不要管的初学者；另一类是自己维护过 agent 环境，被 package manager 那半句话坑过、想知道到底怎么让更新真正跑完的开发者。核心就解决一个问题：怎么让openclaw update不再停在 Skipped 上，或者当它没法继续时，用最快最稳的方式把版本升到最新。我会把原理拆开讲清楚，再给你三种可以直接照做的解决方案，最后附上我实际踩过的坑和排查方法。

1. Skipped 不是错误，先看懂 openclaw update 的更新逻辑

1.1 update 命令内部在做什么

openclaw 的 update 命令遵循一个很常见的双路径设计：先判断“当前这个 openclaw 是什么形态安装的”，再决定走哪条升级路径。判断逻辑通常是这样：找到 openclaw 可执行文件所在目录，看那一层目录下有没有.git目录，或者往上找 git checkout 根。如果有，它就认为你是源码安装，可以执行git fetch、git pull或git checkout完成升级；如果没有，它打印一行说明，然后尝试调用系统中现有的包管理器来升级。

这种设计在很多 node 生态工具里都能看到。npm 全局安装的 CLI 包，安装目录在 node_modules 里，自然没有.git；一键脚本安装的二进制，目录结构更不会带 git 元数据。只有git clone才会留下.git。所以看到 Skipped，本质上只是 update 命令在告诉你：“我判断你不是 git 源码版，git 这条路我不走了。”

后半句and the package manager ...才是关键。不同版本后面跟的话不一样，有时是didn't provide an update path，有时是was not found。无论哪种，它想说的都是同一个意思：git 路径没走，包管理器路径如果不是没装上，就是没能自己跑起来。此时问题的本质不是“openclaw 坏掉了”，而是“你的 openclaw 缺少一条可用的升级通道”。这才是需要你想办法解决的点。

1.2 提示出现的两个前提条件

要复现这个 Skipped 提示，其实需要两个条件同时满足。第一个条件，当前 openclaw 不是 git checkout 形态。比如 npm 装到全局 node_modules 里，或者一键脚本解压到~/.openclaw/bin下，这都不存在.git。第二个条件，包管理器在 update 过程中没有完成更新，所以系统把“跳过 git 更新”这段提示原样输出给你。如果你用的恰好是 git clone 装的方式，那这个提示压根不会出现，update 会直接拉远程代码。

把这两个条件拆开看，就能理解为什么同样一句提示，在不同机器上后续行为完全不同。有人跑完openclaw update后只是看到 Skipped，后面没有任何报错，还成功升级了；有人看到 Skipped 之后就卡住，版本永远不变。差别基本不在 openclaw 本身，而在你机器上那个包管理器是否被正确安装、能否联网、有没有权限。

还有一个容易忽略的点：如果你同时用 npm 装了一份 openclaw，又用官方脚本装了一份 openclaw，那么当你执行openclaw update时，更新的是 PATH 里先命中那个版本。热词里好多人在 Windows 上折腾，最后发现which openclaw指向 WSL 里的路径，而在 PowerShell 里跑 winget 更新的是 Windows 侧路径，两者根本不是同一个文件。这个我会在第 5 部分展开。

1.3 三种安装形态对应的更新路径对照

我把常见安装方式整理成一张表，你先对照自己属于哪一种，再决定接下来的操作。

表格里的“包名”我故意没写死，因为不同版本、不同安装渠道的包名确实有差异。你在 npm 官网或执行npm list -g后能查到，后面有具体命令。官方脚本安装和 npm 安装其实只是“安装方式”不同，数据目录基本都是~/.openclaw，所以升级程序时注意别把数据目录当成源码目录一起删了。

看到 Skipped 不一定代表没升级成功。常见情况是：update 先打出一行 Skipped，紧接着调用了 npm，并把 npm 的输出打在下面。如果你只截取了第一行日志去搜索，很容易误判。所以排查前先把完整日志从头到尾看一遍，看看是不是后面其实已经拉到了新版本，只是你被 Skipped 三个字母吓到了。这是我认为最值得先说明的一点。

1.4 动手前先做一次两分钟诊断

在决定用哪种方案之前，先运行下面这组命令，把环境状态打出来：

which openclaw readlink -f "$(which openclaw)" openclaw --version npm --version 2>/dev/null || echo "no npm" npm list -g --depth=0 2>/dev/null | grep -i -E "openclaw|claw" || echo "not installed via npm" ls -d ~/.openclaw/.git 2>/dev/null || echo "no git dir in ~/.openclaw"

逐行解释一下这几个命令的作用。which openclaw确认你敲的 openclaw 到底在哪个目录；readlink -f是为了穿透软链接，很多 npm 包装其实就是node_modules/@openclaw/cli/bin/cli.js的一个软链接，readlink 之后能看到真实路径。npm list -g看全局包列表里有没有 openclaw，判断是否是 npm 管道装的。最后一行看数据目录里有没有.git，帮助区分“数据目录”和“源码目录”。

诊断结论无非三种。第一，npm 包列表里有 openclaw，那直接用第 2 部分的方法升级。第二，npm 列表里没有，但~/.openclaw/bin存在且能执行，那是脚本安装，直接看第 4 部分重装。第三，存在 git 目录但 update 还是提示 Skipped，说明 update 找错目录了，可以用第 3 部分把 git 源码目录理顺。有了这个判断，后面操作就不会盲目。

2. 方案一：让 package manager 真正接手更新

2.1 先判断 openclaw 是哪个包管理器装的

上一节我们把诊断命令跑完了，这里直接根据结果选路。如果你在npm list -g --depth=0里看到了 openclaw 相关包，恭喜，问题最简单：npm 就是那个 package manager。你甚至不需要理解 openclaw 内部更新逻辑，直接用 npm 把包升到最新就行，效果和openclaw update想做的事一样，而且更可控。

Homebrew 用户可以在终端里查：

brew list | grep -i openclaw brew info openclaw

winget 用户在 PowerShell 里查：

winget list | Select-String -Pattern "openclaw"

需要特别注意：如果你在 WSL 里运行 openclaw，那要查的是 WSL 内部的包管理器（apt、npm、brew），不是 Windows 侧的 winget。很多人的问题是把两个环境的命令混用了。WSL 里装的是 Linux 版本，Windows 侧 winget 装的是 Windows 版本，两个版本各自有各自的~/.openclaw数据目录，别指望一个命令能同时更新两边。

2.2 npm 用户的强制升级命令

确认走 npm 之后，最省事的升级命令是：

npm install -g 你的openclaw包名@latest

为什么不用npm update -g？因为npm update默认按照 package.json 里的 semver 规则更新，如果上游发布的是 breaking change 大版本，update 可能不会跨主版本升级，结果你跑了半天，版本号纹丝不动。npm install @latest则直接拉取 dist-tag 标记为 latest 的版本，完全无视旧版本范围限制，是 CLI 全局工具升级最常用的手段。

装完顺手清理一下缓存和旧包：

npm cache verify npm dedupe -g

这里又回到那个“包名不写死”的问题。你安装 openclaw 的时候，README 里会有明确的安装命令，按那个包名写。如果不确定，先执行npm list -g --depth=0，输出里会列出完整包名，比如@openclaw/cli或openclaw-cli这种。把输出里的名字原样填进 install 命令即可。这一步不能靠猜，猜错了系统会把一个不相干的包升到最新，麻烦更大。

2.3 Homebrew 和 winget 用户的对应操作

如果 openclaw 是通过 Homebrew 安装的，在 macOS 或 Linux 上可以这样更新：

brew update brew upgrade openclaw

第一行brew update先把 Homebrew 自己的索引拉到最新，不然brew upgrade可能找不到刚发布的新版本。Windows 上如果走 winget：

winget upgrade --id OpenClaw.OpenClaw

winget 的upgrade命令可以不加--id，直接winget upgrade会列出所有可更新应用，然后输入编号选择 openclaw。用--id的好处是明确指定对象，避免同名软件混淆。

还有一个反向操作值得提：如果你当时是用 npm 装的，但openclaw update就是不调用 npm，可以试一下把 openclaw 卸载后改用 Homebrew 或官方脚本装，把更新链路切到另一个包管理器上。工具本身没变，变的只是升级入口。很多人卡住就是因为在“哪个包管理器”这个问题上没对齐，切过去之后反而一切都顺了。

2.4 升级后如何确认真的生效了

升级完别急着关终端，至少做三件事确认。第一，看版本：

openclaw --version

第二，确认执行路径没有变化：

which openclaw readlink -f "$(which openclaw)"

第三，如果 openclaw 支持自检，就跑一下：

openclaw doctor

这三件事的逻辑是：版本号确认“内容更新了”，路径确认“你执行的还是那个命令”，doctor 确认“环境没有因为升级而缺依赖”。只要路径指向新装的 node_modules 或 bin 目录，版本号也跳到新版，那openclaw update里 Skipped 的事就可以翻篇了。后续再遇到同样提示，直接记住一句话：Skipped 只是跳过 git 路径，包管理器路径我已经用 npm install 手动补上了。

升级后如果 companion 客户端连接不上，多半不是 CLI 升坏了，而是客户端进程还在后台缓存旧版本。Windows 上先看系统托盘，右键退出 companion，再在任务管理器里确认相关进程没了，重新打开。这个问题出现频率不低，下面排障部分还会单独说。

3. 方案二：补一个干净的 git checkout，恢复源码更新链路

3.1 什么情况下值得折腾源码方式

看到这个提示，很多人是冲着“git checkout”这几个字来的，觉得是不是要把安装目录初始化成 git 仓库才能解决。我的建议相反：绝大多数人不需要折腾源码方式。只有这几类情况才值得：你要改 openclaw 源码；你要跟踪仓库里的最新提交，npm 包发布节奏跟不上；或者你想用git pull作为唯一升级方式，彻底绕开包管理器。否则直接按第 2 部分的方法做最省事。

如果你的需求真的属于这几类，那也不要头脑一热去git init一个已经装了生产数据的目录。源码归源码，数据归数据，最好的做法是保持数据目录~/.openclaw不动，单独克隆一份源码，用源码目录里的 openclaw 命令。这样升级时跑 git pull，风险面小得多。

3.2 推荐做法：源码目录与数据目录分开

我不太建议在一个含数据、配置、认证信息的目录里执行git init然后git checkout -f，因为强制 checkout 可能把当前目录里没有纳入版本控制的文件覆盖或清掉。更稳的做法是：数据留在~/.openclaw，源码克隆到专门目录，比如~/openclaw-source：

mkdir -p ~/openclaw-source git clone 你的openclaw源码仓库地址 ~/openclaw-source cd ~/openclaw-source npm install

源码仓库地址从哪里来？最稳妥的办法是去 openclaw 的官方文档或 GitHub 项目页找 Clone 按钮旁边的地址复制它。你还可以顺便看一眼分支名，现在很多项目主分支叫 main 或 release，后面操作时要对上。

装好依赖后，把源码目录里的可执行文件链接到你 PATH 里的某个目录：

mkdir -p ~/.local/bin ln -sf ~/openclaw-source/bin/openclaw ~/.local/bin/openclaw

前提是~/.local/bin已经在 PATH 里。如果不在，加一行到~/.bashrc或~/.zshrc：

export PATH="$HOME/.local/bin:$PATH"

这样 openclaw 命令指向源码目录，而数据仍然默认落在~/.openclaw。以后更新只需：

cd ~/openclaw-source git pull npm install

源码更新链路就彻底重建了。openclaw update再也不会报 Skipped，因为当前可执行文件确实在一个 git checkout 里。

3.3 源码目录怎么升级、怎么回滚

源码方式下，日常升级我一般不用 openclaw 自带的 update，而是手动三步：进入源码目录，git pull 拉取最新提交，然后看依赖有没有变化，有就重装依赖。因为源码仓库里 package.json 变了而 node_modules 还是旧的，是源码方式最常见的翻车原因。

cd ~/openclaw-source git pull git log -1 --oneline npm install ./bin/openclaw --version

回滚也有固定动作。先用git log --oneline -5看最近的提交历史，记下要回退到的提交哈希，然后：

git checkout 你要回滚的提交哈希 npm install

如果你不想长期停在旧提交，想把当前分支 reset 到某个位置，用git reset --hard 哈希。注意，reset 之后要想再拉远程新代码，需要先git reset --hard origin/分支名或重新 checkout 分支。这个操作会把本地未提交改动丢掉，动手前确保没有正在改的代码。

升级过程中如果 npm install 报错，先看 lock 文件。源码仓库里大概率有 package-lock.json 或 npm-shrinkwrap.json，直接npm ci比npm install更可靠，因为 ci 会严格按照 lock 文件安装，不会尝试升级依赖，能复现出开发者当时的环境。

3.4 这个方案的边界和容易踩的坑

源码方式最大的坑就是目录混用。很多人把源码 clone 到~/.openclaw，结果认证信息、会话记录、插件数据全被 git 操作搞乱。所以再次强调，源码放源码目录，数据放数据目录，两者通过默认路径关联，而不是放在同一个目录里互相污染。

第二个坑是 PATH 顺序。你链接了源码 bin 到~/.local/bin，但如果系统里还残留着 npm 全局版或脚本版 openclaw，且它们的目录排在~/.local/bin前面，那么执行 openclaw 时还是会命中旧版。用which -a openclaw可以把所有候选路径列出来，type openclaw能看到实际选中哪一个。发现顺序不对，就把旧的 wrapper 删掉，或者调整 PATH 顺序。

第三个坑跟 git 分支有关。某些项目用 release 分支而不是 main 分支发布，你 clone 下来默认在 master/main，git pull 只能拉自己所在分支。如果 openclaw 的日常更新切的是 release 分支，你需要先git checkout release，否则每次 git pull 看似成功，实际版本可能一直不往前走。这一点在文档里很容易被忽略，我一开始也被“pull 了但版本不变”坑过一次。

4. 方案三：干净重装做兜底

4.1 先备份：~/.openclaw 里都有什么

如果包管理器方案失败、源码整理又太复杂，干净重装是最后的兜底。但重装之前必须先搞清楚~/.openclaw里有什么，因为它不光是程序目录，更是 agent 的数据目录。正常情况下，这个目录里会有配置文件、认证凭据、会话记录、索引数据库等。丢了数据再想恢复，往往比解决 Skipped 提示麻烦十倍。

备份最简单的命令是：

cp -a ~/.openclaw ~/.openclaw.bak.$(date +%Y%m%d)

Windows 环境对应：

Copy-Item -Recurse -Force $env:USERPROFILE\.openclaw $env:USERPROFILE\.openclaw.bak

备份完成后，先别急着删任何东西。我习惯把“关键配置”再单独复制一份到备份目录之外，比如~/.openclaw里的设置文件、认证文件单独拷出一份，因为后面恢复配置时，整目录覆盖容易把新版生成的默认文件也覆盖掉，而单独拷文件更可控。具体文件名以你自己目录里的为准，不要照搬这里猜测的名字。

4.2 卸载时把“删程序”和“删数据”分开

重装最忌讳的就是一个rm -rf ~/.openclaw把所有东西全删了。虽然这是很多人的第一反应，但你把程序和配置一起删掉之后，新版 openclaw 虽然能重新生成默认配置，你的认证和会话记录都没了。正确做法是只删程序，保留数据目录。

不同安装方式删程序的方法不同。npm 安装的用：

npm uninstall -g 你的openclaw包名

脚本安装的，先找到 install 时生成的安装目录，通常是~/.openclaw/bin或安装在系统级路径下的目录，把这个目录删掉，再把 PATH 里的 wrapper 入口删掉。源码安装的，删除源码目录~/openclaw-source即可，数据目录动都不要动。

这里再说一个容易混淆的点：openclaw 的可执行程序如果本身放在~/.openclaw/bin/openclaw，而数据也在~/.openclaw，那么你不能为了删程序把整个~/.openclaw删了。正确姿势是把~/.openclaw/bin这个子目录删掉，或者执行官方提供的卸载脚本。如果找不到卸载脚本，宁可先放着，等新版本安装好后再手动覆盖 bin 目录，也别贸然整目录删除。

4.3 重新安装到最新版

程序清理干净后，选一种安装方式装最新版。一般有两种：官方安装脚本和 npm 全局安装。我不建议在这里手动编造一段 install 脚本地址，最稳的是去项目 README 或官网复制当时的安装命令。对于包管理方式，你已经知道包名了，直接：

npm install -g 你的openclaw包名@latest

如果是脚本方式，把 README 里那行安装命令原样执行。两种方式装出来都是最新版，区别主要体现在后续更新方式上。

装完后不要急着验证功能，先把备份的配置恢复过来。策略是：让新版先跑一次，生成默认配置，然后用刚才单独备份的配置文件覆盖默认文件，只覆盖你知道要保留的那些，不要整目录覆盖。比如认证文件、设置文件。如果新版对配置格式有调整，默认配置会写清楚，你手工把旧配置里的关键字段迁移过去，比直接覆盖更安全。

最后跑一遍：

openclaw --version openclaw doctor

如果 doctor 能过，环境基本就回来了。这时再看~/.openclaw里有没有混进旧版遗留给你的垃圾文件，比如.git目录、临时文件，没有的话就可以放心用。

4.4 Windows/WSL 环境的重装注意事项

热词里有人提到“openclaw 无法安全验证 wsl2 环境，请在 powershell 中运行 wsl -- status”，这个在重装环节很值得讲。如果你的 openclaw 跑在 WSL 里，先确认 WSL 版本。在 PowerShell 里：

wsl --status

输出应该能看到默认版本是 2。如果显示 WSL1，执行：

wsl --set-default-version 2

然后重启 WSL 再继续。因为 WSL1 和 WSL2 的文件系统、运行时表现差异很大，很多 openclaw 在 WSL1 上的诡异问题在切到 WSL2 后直接消失。这不算 openclaw 的 bug，而是运行环境不达标造成的连锁反应。

Windows 重装还有一个坑：Windows 侧的 companion 客户端和 WSL 里的 CLI 是两套东西。如果你主要用 companion，那升级对象应该是 companion 客户端，而不是在 WSL 里升 CLI；反之，如果你用 CLI 启动 runtime，再让 Windows 侧工具去连，两边版本最好保持同步，否则很容易出现“CLI 显示最新版，companion 却连不上”的错配问题。每次重装后，先在一个环境里把版本确认清楚，再去动另一个环境，避免两头各有一份互相打架。

5. 排障实录：我踩过的坑和排查方法

5.1 两条 openclaw 命令并存，PATH 指向旧版

我最早遇到 Skipped，就是典型的“多版本并存”。当时机器上既跑过官方脚本，又装了 npm 包，which openclaw显示的是/usr/local/bin/openclaw，我以为只有一个。后来用which -a openclaw才发现，还有第二个在~/.openclaw/bin/openclaw，并且因为 PATH 里~/.openclaw/bin排在前面，实际执行的一直是旧脚本版。

这个问题特别容易漏。因为which默认只显示第一个命中，你用which查出来一个路径，以为万事大吉，其实系统里还有另一个版本躲在别的目录。排查时必须用：

which -a openclaw

把所有命中列出来，再逐个看版本：

/usr/local/bin/openclaw --version ~/.openclaw/bin/openclaw --version

发现旧版残留后，删除旧 wrapper 或把它移出 PATH。如果你不想删，也可以把 PATH 里你自己那份源码 bin 目录挪到最前面，让新版本永远先命中。我的经验是：删除残留比调 PATH 更彻底，不然每次终端启动都要看 PATH 脸色。

5.2 npm 全局目录权限不足

第二个高频问题是 npm 更新时权限不够。如果你看到类似EACCES: permission denied, access '/usr/local/lib/node_modules'的报错，说明 npm 的全局目录是系统级目录，而当前用户没有写权限。这通常发生在直接用系统自带 Node 安装 npm 包的场景，而用 nvm 或 fnm 这类版本管理器装 Node 的用户很少遇到。

最快的解决方案是重装 Node 到用户目录下，然后让全局包默认落在用户目录。nvm 装完 Node 后，npm 全局目录一般在~/.nvm/versions/node/.../lib/node_modules，不需要 sudo 就能装包。这样做还有一个额外好处：以后 npm 升级任何全局工具都不会再被权限问题骚扰。

如果暂时不想动 Node 环境，也可以用 sudo 临时升级：

sudo npm install -g 你的openclaw包名@latest

升级后注意文件属主可能混了。根目录安装的文件归 root，普通用户执行 openclaw 时如果它要写全局 node_modules，还是会报权限。所以治本还是换 nvm，治标才是 sudo。

5.3 companion 还在跑旧 runtime

这类 GUI 工具最容易出现“命令升级了，但图形端还在跑旧版本”的错位。OpenClaw 的 companion 客户端如果一直开着，它可能启动时就把 runtime 进程拉起来了，你后面在命令行里升级 CLI，它根本不知道。表现就是：openclaw --version已经是最新版，companion 界面里版本号还是旧的，甚至报连接失败。

解决办法很简单但是容易被忽略：彻底退出 companion，而不是只关窗口。Windows 上右键系统托盘图标退出，再打开任务管理器确认进程已经不在；macOS 上右键 dock 图标选择退出。退出后用命令行启动一次 openclaw 或重启 companion，让它重新拉起 runtime。这个小问题在文档里经常只写一句“重启服务”，新手很容易理解成关个窗口就行，结果反复折腾还以为是 bug。

5.4 常见现象速查表

把前面所有内容浓缩成一张速查表，方便你以后排查：

这张表不覆盖所有极端场景，但覆盖了我从实际运维中看到的最典型几种。如果你遇到表中没有的情况，建议先跑一遍第 1.4 小节的诊断命令，把哪个环境、哪种安装方式、哪个版本号记下来再去搜，错误信息和环境信息全一点，别人也更容易帮你定位。

5.5 几个平时文档里不写的经验

最后说点文档里一般不写的个人经验。第一，看到 Skipped 第一反应不应该是“出错了”，而是“这对我的安装方式来说是正常的”。我见过太多人为了消掉这个提示，非要给数据目录 git init，结果把配置搞乱。没必要。有没有真正完成升级，看的是版本号和能否跑起来，不是看日志里有没有 Skipped。

第二，升级 openclaw 前，先记录当前版本号，再执行升级。这看起来多此一举，但当你发现升级后行为变了、数据目录不兼容时，旧版本号就是你回滚的依据。npm 包装回滚特别方便：

npm install -g 你的openclaw包名@你想回滚的版本号

源码方式回滚用 git checkout 哈希。脚本安装方式就没这么优雅了，得去找旧版安装包，所以备份数据永远不亏。哪怕只是把~/.openclaw打成压缩包放一边，也比到时候后悔强。

第三，不要同时维护两条更新链路。今天用 npm 升，明天用 git pull，后天又用官方脚本重跑一遍，很容易配置乱掉。选定一种安装方式之后，日常就只走这一种。遇到 Skipped，要么接受它、用包管理器处理，要么整体切换成源码方式。最忌讳的是混着用，最后哪个版本都说不清。

最后再分享一个我自己的实操习惯：每次升级前，我会先在终端里跑openclaw --version记下旧版本号，然后备份~/.openclaw目录，再执行升级命令。等版本确认更新后，我会再跑一次openclaw doctor，如果 doctor 报任何环境相关的问题，就回滚到旧版本号，而不是继续在坏环境上排查。这套流程虽然多两步，但很少会被“升级后环境也坏了”这种事卡住。

关于那个 Skipped 提示，我的总体态度是：它不是敌人，只是一个需要被你理解的信号。它告诉你 openclaw 的 git 更新链路没接上，剩下的决策权在你自己。你可以什么也不管，只要包管理器能更新就行；也可以换个方式，把源码链路补上，一劳永逸。选择权在你自己手里，但前提是别再把它当成报错去瞎折腾。希望这篇东西能帮你少走一点弯路。