技爪网
技爪网

技术问题排障知识库

首页/软件安装与配置/OpenClaw 安装与删除全流程方案（macOS 篇）
软件安装与配置

OpenClaw 安装与删除全流程方案（macOS 篇）

在 macOS 上使用 OpenClaw，最稳妥的思路不是先装再说，而是按安装、初始化、验证、删除、残留清理这五步来做。本文从官方文档出发，带你完成完整流程。

发布时间：2026年3月28日 16:39阅读量：4

一、安装前你需要准备什么

在 macOS 上，官方文档建议使用 Node 24，同时说明 Node 22.14+ 也受支持；如果你走官方安装脚本，这部分通常会自动处理。除此之外，你还需要一个可用的模型提供商凭据，例如 OpenAI、Anthropic、Google 等的 API Key，因为 onboarding 过程中会要求你完成认证。

从定位上说，OpenClaw 是一个运行在你自己设备上的自托管 Gateway，负责把 Telegram、WhatsApp、Discord、iMessage 等聊天入口接到 AI agent 上；因此它不是一个只点开就用的单纯桌面 App，而是 CLI + Gateway + 配置目录 + 可选 macOS companion app 的组合。

二、推荐安装方式：官方安装脚本

对于大多数 macOS 用户，最推荐的安装方式就是官方安装脚本：

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

官方安装页说明，这个脚本会自动识别操作系统、在需要时安装 Node、安装 OpenClaw，并启动 onboarding 流程。

如果你只想先把程序装上，不想立刻进入初始化向导，可以这样安装：

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

这是官方提供的仅安装、不立即引导配置的标准方式。

三、手动安装方式：适合已经自己管理 Node 的用户

如果你的 macOS 机器已经装好了 Node，并且你更习惯自己控制全局包安装，那么可以直接用 npm 或 pnpm：

1）npm 安装

bash
npm install -g openclaw@latest
openclaw onboard --install-daemon

2）pnpm 安装

bash
pnpm add -g openclaw@latest
pnpm approve-builds -g
openclaw onboard --install-daemon

官方文档明确给出了这两种方式，并特别说明：pnpm 需要额外执行 pnpm approve-builds -g，因为某些带构建脚本的包默认不会自动放行。

如果你是开发者，想从源码运行，也可以走源码安装路线：

bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm link --global
openclaw onboard --install-daemon

这条路径更适合本地调试、二次开发或跟进主分支更新，不适合普通用户的首装。

四、初始化配置：真正让 OpenClaw 跑起来

安装 CLI 只是第一步，真正让 OpenClaw 可用的是 onboarding。官方 Getting Started 页面给出的主线命令是：

bash
openclaw onboard --install-daemon

这个向导会带你完成模型与认证方式选择、Gateway 参数、工作目录、渠道配置以及后台服务安装；在本机模式下，它还会把 Gateway 作为后台服务装好。

官方 onboarding 参考也说明了一个很重要的行为：如果你的 ~/.openclaw/openclaw.json 已经存在，重新跑 onboarding 时默认不会直接清空现有配置，而是让你选择 Keep、Modify 或 Reset。也就是说，重跑初始化并不等于重装。

五、安装完成后，必须做的 4 个验证动作

装完以后，不要直接开始配渠道。先确认这套环境真的可用。

1）确认 CLI 已安装

bash
openclaw --version

2）检查配置或迁移问题

bash
openclaw doctor

3）确认 Gateway 状态

bash
openclaw gateway status

4）做一次整体健康检查

bash
openclaw health

官方安装页把 openclaw --version、openclaw doctor、openclaw gateway status 列为标准验证动作；而 macOS 稳定工作流文档则把 openclaw health 作为 sanity check。默认情况下，Gateway 会监听在 18789 端口。

如果你只想看 Gateway 服务层面的控制命令，官方还给出了这一组常用命令：

bash
openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

这些就是 macOS 上最常用的日常运维入口。

六、macOS App 要不要装

如果你只想通过 CLI 跑 OpenClaw，其实可以不依赖 macOS app；但如果你需要菜单栏状态、系统权限申请、通知、麦克风、屏幕录制、Canvas、system.run 这类 macOS 能力，那么 companion app 很有价值。官方文档把它定义为 menu-bar companion，负责持有 TCC 权限、连接或管理本地 Gateway，并把 macOS 能力暴露给 agent。

它的典型本机使用流程是：

  1. 安装并启动 OpenClaw.app
  2. 完成权限引导
  3. 确认 Local 模式下 Gateway 正常运行
  4. 需要命令行时再安装 CLI

这套流程在官方 macOS onboarding 和 setup 文档里都有说明。

另外，官方 macOS 文档还提到：这个 App 本身可以按需帮你安装全局 openclaw CLI；如果你使用的是 Local 模式，它会优先附着到本地已有 Gateway，如果没有，再通过 openclaw gateway install 启用本地 launchd 服务。

七、删除 OpenClaw：最推荐的卸载方式

如果你想删除 OpenClaw，最推荐的是直接用官方内置卸载命令，而不是手工乱删目录：

bash
openclaw uninstall

如果你想非交互式一次删干净：

bash
openclaw uninstall --all --yes --non-interactive

官方 CLI 文档说明，openclaw uninstall 会卸载 Gateway 服务和本地数据，但 CLI 本身默认会保留；如果你怕误删，还可以先做备份：

bash
openclaw backup create
openclaw uninstall

这些都是官方给出的标准卸载路径。

八、手动彻底删除：适合想清到最干净的人

如果你想把 OpenClaw 在 macOS 上尽量删干净，可以按官方卸载页的顺序来：

第一步：停止 Gateway

bash
openclaw gateway stop

第二步：卸载 Gateway 服务

bash
openclaw gateway uninstall

第三步：删除状态目录和配置

bash
rm -rf "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"

第四步：删除工作目录（可选）

bash
rm -rf ~/.openclaw/workspace

第五步：删除 CLI

bash
npm rm -g openclaw

如果你当初不是用 npm，也可以改成：

bash
pnpm remove -g openclaw

或者：

bash
bun remove -g openclaw

第六步：如果装过 macOS App，再删 App

bash
rm -rf /Applications/OpenClaw.app

以上就是官方文档给出的手动达到同等卸载结果的标准顺序。官方还特别提醒：如果你用了自定义 OPENCLAW_CONFIG_PATH，并且它不在默认状态目录里，要记得额外删除那个配置文件；如果你用了 profile，多 profile 的状态目录一般会在 ~/.openclaw-<profile>，需要逐个清理。

九、如果 CLI 已经没了，但后台服务还在跑，怎么删

这是 macOS 用户最容易碰到的残留问题：命令行已经用不了，但 LaunchAgent 还活着。官方卸载页给了一个纯 launchd 的手动清理方式：

bash
launchctl bootout gui/$UID/ai.openclaw.gateway
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist

如果你用过 profile，就把标签和 plist 名称替换成 ai.openclaw.<profile>。官方也提醒，旧版本可能还残留 com.openclaw.* 这样的 legacy 标签和 plist，一并删掉更稳妥。

十、删完以后，macOS 权限弹窗记录怎么处理

如果你装过 macOS companion app，即使 App 删了，系统的权限记录有时还会留着。官方权限页给的恢复思路是：

  1. 先退出 App
  2. 到 系统设置 → 隐私与安全性 里移除对应应用条目
  3. 重新从同一路径启动 App 再授权
  4. 如果提示仍不出现，再用 tccutil 重置
  5. 某些权限要重启 macOS 才会重新弹出

这组建议主要是为重装后权限不弹、权限状态异常准备的。

十一、最常见的两个坑

1）安装成功了，但终端里提示 openclaw: command not found

官方安装页直接给了排查顺序：

bash
node -v
npm prefix -g
echo "$PATH"

如果全局安装目录的 bin 没进 PATH，可以把下面这一行加到 ~/.zshrc 或 ~/.bashrc：

bash
export PATH="$(npm prefix -g)/bin:$PATH"

然后重开一个终端窗口。

2）执行 openclaw gateway stop 之后，再 start 起不来

这是一个近期在 GitHub 上被报告过的 macOS 问题：某些环境里，stop 会把 LaunchAgent 从 launchd 注册表里移除，后续 start 不能自动重新注册，恢复办法是重新安装服务。官方 Gateway 文档本身也说明了：如果你修改了路径、配置或环境，或者服务状态不对，可以用强制重装服务的方式恢复。

实操上可以直接用：

bash
openclaw gateway install --force
openclaw gateway status

这通常比反复 stop/start 更稳。

十二、给 macOS 用户的最终建议

如果你是第一次装 OpenClaw，最稳妥的路线是：

  1. 用官方安装脚本安装
  2. 运行 openclaw onboard --install-daemon
  3. 用 openclaw gateway status 和 openclaw health 验证
  4. 需要系统权限、菜单栏和 Mac 能力时，再配合 OpenClaw.app 使用
  5. 以后如果要删除，优先用 openclaw uninstall，想删彻底再补手工清理

这样做的好处是：安装路径清晰、验证步骤明确、出问题时也知道该从 CLI、Gateway、LaunchAgent、状态目录哪一层往回查。整个流程都和当前官方文档保持一致。

问题求助

没能解决你的问题？直接问我

如果你遇到任何技术问题无法解决，可以在这里提交求助。我会尽快查看并回复你。

支持作者

如果这篇文章帮到了你，可以支持我

扫码打赏，支持我持续更新原创排障文章。

打赏二维码