OpenClaw快速安装指南（Mac版）

一键安装脚本

如果你想要最快速的安装方式，可以创建一个安装脚本：

#!/bin/bash

echo "🚀 开始安装OpenClaw..."

# 1. 安装Homebrew（如果尚未安装）
if ! command -v brew &> /dev/null; then
    echo "📦 安装Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
fi

# 2. 安装Node.js
echo "📦 安装Node.js..."
brew install node

# 3. 安装Python 3.10
echo "📦 安装Python 3.10..."
brew install [email protected]

# 4. 安装OpenClaw
echo "📦 安装OpenClaw CLI..."
npm install -g @openclaw/cli

# 5. 初始化配置
echo "⚙️  初始化OpenClaw..."
openclaw init --quick

echo "✅ 安装完成！"
echo "📋 接下来运行："
echo "   openclaw gateway start  # 启动服务"
echo "   openclaw web            # 打开Web界面"

保存为 install-openclaw.sh，然后运行：

chmod +x install-openclaw.sh
./install-openclaw.sh

先选哪条路：快速安装 vs 完整安装

如果你只是想 先把 OpenClaw 跑起来，优先走这篇里的“快速安装”路径：

• 适合：第一次上手、只想先验证本机能跑、先开 Gateway / Web UI 看效果
• 优点：步骤少、启动快、适合边装边测
• 代价：很多高级配置、Provider 细节、长期维护策略不会在第一轮就讲完

如果你已经确定要长期用，或者准备做更复杂的模型/插件/多端接入，建议转去更完整的安装路线：

• 适合：准备长期部署、要接更多 Provider、想从一开始就把结构搭稳
• 优点：后面少返工
• 代价：前期阅读量更大

建议用法： 先按这篇把最小可用环境跑通，再继续看完整安装与故障排查文档，而不是一上来就把所有配置一次配满。

FAQ：安装前后最容易误判的 4 个问题

安装命令到底该用哪个？

这一点最容易搜到旧答案，也最容易把新用户带偏。

先记结论： 不要默认搜索结果里看到什么就执行什么，先确认当前官方 CLI 名称与安装方式。

建议在安装前先做这 3 步核对：

openclaw --version
npm list -g --depth=0 | grep openclaw
pnpm list -g --depth=0 | grep openclaw

如果你机器里曾经装过旧包名、旧全局命令、或者同时混用 npm / pnpm，两类问题最常见：

• 你以为自己升级了，其实 shell 里调用的还是旧 CLI
• 你以为是 OpenClaw 本体坏了，实际上是全局包来源不一致

更稳的做法是：确定一个包管理器作为主入口，然后把旧的全局残留清掉，再重新验证版本与路径。

为什么明明装好了，openclaw 还是不能用？

这通常不是“没安装”，而是“shell 看到的不是你刚装的那个命令”。

先查 4 件事：

which openclaw
command -v openclaw
npm prefix -g
pnpm bin -g

如果 which openclaw 指向的目录不在当前 shell 的 PATH 前列，你后面所有排查都会偏掉。

处理顺序建议是：

1. 先确认当前 shell 实际使用的命令路径
2. 再确认这个路径对应的是哪套全局包管理前缀
3. 最后再决定是修 PATH，还是重装 CLI

启动后网页能打开，但功能不正常，先看什么？

如果 Web UI 能开，但很多功能不工作，不要只盯着浏览器。

优先看这几项：

openclaw gateway status
openclaw logs
openclaw doctor

这三步的意义分别是：

• gateway status 看服务是否真的健康
• logs 看启动期是否有 provider / plugin / assets 报错
• doctor 看配置和运行环境有没有结构性问题

很多“界面能开但功能坏”的根因，其实是：

• provider 没配好
• 资产没构建完整
• 插件启动失败
• 本机路径或权限异常

第一次装好后，最小可用验证要怎么做？

不要装完就直接上复杂集成。先做一个最小闭环：

1. 确认 CLI 可用
2. 确认 gateway 能启动
3. 确认 Web UI 能打开
4. 确认至少一个模型 provider 能正常返回
5. 再去接聊天渠道、技能或自动化任务

建议最少跑下面这组检查：

openclaw --version
openclaw gateway status
openclaw doctor

如果这三步都不稳，先别继续往上叠功能。

FAQ：Mac 安装最容易卡住的 4 类问题

1) Node 版本到底怎么选？

最稳的原则不是“越新越好”，而是：

• 优先使用 当前 OpenClaw 已验证/常见的 LTS 或项目正在使用的 Node 版本
• 如果你已经装了特别新的 Node，遇到依赖编译、插件加载、前端资源异常，先别急着怀疑 OpenClaw，本地 Node 版本就是第一嫌疑人

实用建议：

node -v
which node

如果你切过很多版本管理器（如 nvm / fnm / asdf），还要确认当前 shell 里实际生效的是哪一个 Node。

2) Apple Silicon 和 Intel 的差异主要在哪？

macOS 上最常见的差异不在 OpenClaw 本身，而在包管理路径：

• Apple Silicon 常见 Homebrew 路径：/opt/homebrew
• Intel 常见 Homebrew 路径：/usr/local

所以遇到“命令存在但找不到”“明明装了却没生效”，先检查：

which brew
brew --prefix
which node
which python3

很多所谓“安装失败”，其实是 PATH 指到了另一套旧环境。

3) Web UI 打开后资源异常 / 插件加载不全怎么办？

先按这个顺序查，不要一上来重装系统：

1. 看状态：

openclaw gateway status

2. 看日志：

openclaw logs

3. 确认当前 Node / pnpm / 构建环境是不是对的
4. 如果是源码安装或前端资源异常，考虑重新安装依赖并重建
5. 最后再重启 Gateway

核心思路是：先确认是服务没起来、资源没构建、还是环境路径错了。

4) Homebrew 路径不一致会导致什么问题？

最常见表现：

• brew install 成功了，但命令不可用
• openclaw / node / python3 指向了不同前缀
• 同一台机器上同时有 /usr/local 和 /opt/homebrew，结果 shell 实际走的是旧路径

快速检查：

echo $PATH
which brew
which node
which openclaw

如果路径混乱，先把 shell 配置收敛，再继续装，不然越装越乱。

如果这是你从首页进入的第一篇 OpenClaw 页面

GA4 现在把中文首页、2026.3.13 发布说明和这篇 Mac 安装指南放在同一条低流量发现路径里。这里应该承担“安装检查点”的角色，而不是把读者留在安装页里结束。

• 刚从首页进来的新访客：先完成 Mac 安装，再去 安装成功检查清单 验证 CLI、Gateway、Web UI 和模型响应。
• 正在比较当前版本的读者：安装可用后再读 2026.3.13 发布说明，避免把版本特性和安装失败混在一起。
• 已经遇到命令卡顿的读者：不要反复重装，直接看 CLI 性能回归分诊。

这样 Mac 安装页仍然专注安装，同时给搜索和首页访客一个更符合真实意图的下一步。

最小化配置示例

创建最小配置文件 ~/.openclaw/openclaw-minimal.json：

{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "你的DeepSeek API密钥",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat"
          }
        ]
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local"
  }
}

然后使用此配置启动：

openclaw --config ~/.openclaw/openclaw-minimal.json gateway start

首次运行验证：证明这台 Mac 真的可用

脚本跑完以后，不要把“安装完成”直接等同于“环境可用”。更稳的首次验证顺序是：

1. 先跑 openclaw --version，确认命令来自你预期的包管理器路径。
2. 用 openclaw gateway status 启动或检查 Gateway，再继续打开其他工具。
3. 只有 Gateway 显示健康后，再打开 Web UI，避免浏览器报错掩盖服务启动问题。
4. 先跑一个很小的模型或 agent 动作，再接插件、聊天渠道或自动化。
5. 把 Node 版本、安装方式、第一条成功命令记进自己的环境记录。

这样 Mac 用户会有一个明确的通过/失败检查点：如果 CLI 存在但 Gateway 起不来，就继续留在安装排障；如果 Gateway 健康但真实任务失败，就转去运行时排障，而不是反复重装同一批包。

常用命令速查表

服务管理

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

# 查看状态
openclaw gateway status

配置管理

# 查看配置
openclaw configure --show

# 设置API密钥
openclaw configure --set models.providers.openai.apiKey=你的密钥

# 重置配置
openclaw reset --config

诊断工具

# 健康检查
openclaw doctor

# 查看日志
openclaw logs

# 查看版本
openclaw --version

Mac 安装后第一条任务冒烟测试

CLI 能启动后，不要立刻把 Mac 安装标记为完成，先跑一条很小的真实任务。它至少要证明四件事：OpenClaw 能读到配置、选定的模型 provider 能返回真实 assistant 消息、一个安全的本地工具能执行、session transcript 会写到预期位置。

最好的冒烟测试应该很无聊：让 agent 检查一个无风险的项目文件，用一句话总结，然后确认这个 session 可以继续恢复。如果这一步失败，优先按安装或权限问题处理，而不是把它误判成 prompt 质量问题。

快速测试安装

安装完成后，运行这个测试脚本验证所有功能：

#!/bin/bash

echo "🧪 开始测试OpenClaw安装..."

# 测试1: CLI是否可用
if command -v openclaw &> /dev/null; then
    echo "✅ CLI已安装"
    openclaw --version
else
    echo "❌ CLI未找到"
    exit 1
fi

# 测试2: 启动网关
echo "🚀 启动网关服务..."
openclaw gateway start --background

sleep 3

# 测试3: 检查网关状态
if openclaw gateway status | grep -q "running"; then
    echo "✅ 网关服务运行正常"
else
    echo "❌ 网关服务启动失败"
    exit 1
fi

# 测试4: 检查Web接口
echo "🌐 测试Web接口..."
if curl -s http://localhost:18789/health > /dev/null; then
    echo "✅ Web接口可访问"
else
    echo "❌ Web接口不可访问"
fi

# 测试5: 停止服务
echo "🛑 停止网关服务..."
openclaw gateway stop

echo "🎉 所有测试完成！OpenClaw安装成功。"

故障排除速查

问题：命令未找到

# 解决方案：重新链接
npm link @openclaw/cli
# 或
export PATH="/usr/local/bin:$PATH"

问题：端口冲突

# 解决方案：使用其他端口
openclaw gateway start --port 18790

问题：Python版本错误

# 解决方案：设置正确版本
export PATH="/usr/local/opt/[email protected]/bin:$PATH"

问题：权限不足

# 解决方案：修复权限
sudo chown -R $(whoami) ~/.openclaw

谁应该先看这篇快速安装指南

如果你想要的是下面这些结果，这一页就是更合适的入口：

• 先用最快速度把 OpenClaw 在 Mac 上跑起来
• 先验证本机的 Node、Python、Homebrew、Gateway 路径是不是基本健康
• 先判断这台机器能不能达到最小可用安装，再决定是否继续深配
• 先比较快速启动路径和完整安装清单的成本差异

如果你已经确定要做长期部署、多 provider 配置，或者需要可复制给团队的更稳安装流程，那么完整安装指南通常更适合作为主入口。

常见快速安装判断问题

什么时候该先看 quick install，而不是完整安装指南

当你更在意速度，而不是一次性把所有细节配完整时，就应该先走 quick install。它特别适合本机验证、演示环境、个人初次搭建。如果你要写成长期可维护的部署流程，完整安装指南更能减少后续返工。

什么时候 quick install 失败，说明该切去排障而不是继续重装

如果 CLI 已经装上了，但 gateway status、doctor、Web UI 访问仍然过不了，而且基础路径与版本也已经核对过，就别再把它当成单纯的 quick install 问题。这时更常见的瓶颈是环境不一致、权限、provider 配置或运行时健康度，所以应该直接切到排障清单。

Docker安装方式（备选）

如果你更喜欢使用Docker：

# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

# 进入容器执行命令
docker exec -it openclaw openclaw --help

更新OpenClaw

# 检查更新
npm outdated -g @openclaw/cli

# 更新到最新版本
npm update -g @openclaw/cli

# 或者重新安装
npm install -g @openclaw/cli@latest

卸载OpenClaw

# 1. 停止所有服务
openclaw gateway stop

# 2. 卸载CLI
npm uninstall -g @openclaw/cli

# 3. 删除配置文件（可选）
rm -rf ~/.openclaw

# 4. 删除日志文件
rm -rf /tmp/openclaw

下一步优先覆盖的精确 Mac 安装搜索词

当读者从 Mac 安装类搜索进入这里，重点是用最短安全路径从下载走到可用的 OpenClaw gateway，而不是停留在泛泛安装说明。

• OpenClaw install Mac quick guide：先安装应用、确认 gateway 启动，再打开本地 dashboard，最后再接 channel 或 provider。
• OpenClaw macOS setup gateway not reachable：先查 gateway 进程是否运行、本地端口是否被拦、浏览器 URL 是否指向预期地址。
• OpenClaw Mac install permission issue：先在 macOS 安全设置里批准应用，再重新跑 smoke test，不要反复重装。

从 Mac 安装流量转成首次成功检查清单

如果你是因为 OpenClaw Mac 快速安装搜到这里，安装完成后不要只看命令是否跑完。真正应该验收的是首次成功路径：本地 CLI 能启动、Gateway 状态可读、浏览器或渠道能打开会话、以及一次最小任务能拿到稳定回复。

最小检查清单包括：记录 openclaw gateway status 输出、确认当前配置文件位置、保存一次成功会话 URL 或 session id，并把失败时的 shell、Node 版本和安装方式写进排查记录。这样安装流量会被引导到“首次运行、配置确认、故障定位”三类高意图入口，而不是停在下载步骤。

相关阅读

• OpenClaw 完整安装指南
• OpenClaw Agent 排障清单
• 安全与成本

下一步阅读（建议按顺序）

如果你已经把基础环境跑起来，下一步建议看：

1. 技能与扩展
   • /zh/news/mastering-openclaw-skills
   • /zh/news/creating-custom-skills-openclaw
2. 通用故障排查
   • /zh/news/troubleshooting-openclaw-agents
3. 近期高价值排障更新
   • /zh/news/fix-codex-oauth-legacy-openai-codex-override
   • /zh/news/mattermost-plugin-fails-to-load-in-openclaw-2026-3-7

这样走的好处是：先把安装跑通，再补能力，再补排障，而不是把所有问题都压在第一次安装里解决。

获取帮助

• 查看完整文档：openclaw --help
• 查看特定命令帮助：openclaw <command> --help
• 访问官方文档：https://docs.openclaw.ai
• GitHub问题跟踪：https://github.com/openclaw/openclaw/issues

---

提示：安装过程中遇到问题，可以查看详细日志：

tail -f ~/.openclaw/logs/gateway.log

搜索入口分流：Mac 安装卡住时先判断什么

如果你是从 “OpenClaw Mac 安装”、“openclaw install mac” 或 “npm/pnpm 安装 OpenClaw 失败” 搜到这里，先按这四步缩小范围：

1. 先确认 Node 版本：优先使用当前项目支持的 LTS 版本，避免用系统自带旧 Node 直接安装。
2. 区分安装失败和启动失败：包管理器报错先看 npm/pnpm、网络和权限；能安装但启动失败，再看配置、端口和登录态。
3. 不要混用全局安装来源：Homebrew、npm global、pnpm global 混在一起时，最容易出现命令路径指向旧版本。
4. 保留第一条真实错误：后续重试常会产生噪声，排障时最有价值的是第一次失败的完整日志和当前 shell 环境。

Mac 安装问题的关键不是“多试几遍”，而是先确认失败发生在依赖安装、命令解析、配置加载，还是第一次启动。

相关阅读

• OpenClaw 完整安装指南：自托管搭建、检查点与常见坑
• OpenClaw Agents 排障指南：任务卡住、工具不回、结果异常时先查什么
• OpenClaw 更新指南（2026-02-02）：升级前后该重点检查什么
• OpenClaw 记忆系统指南：什么该记、什么不该记、记住后怎么补验