怎么在 Mac 上安装 OpenClaw？

先安装 Homebrew、Node.js、Python 3.10+ 和 Git，再安装 OpenClaw CLI，运行初始化流程，最后启动 gateway 验证安装是否成功。

安装 OpenClaw 前需要准备什么？

通常需要 macOS 10.15 或更高版本、足够的内存和磁盘空间、可用网络，以及 Homebrew、Node.js、Python 3.10+、Git 这些本地开发依赖。

为什么 OpenClaw 在 Mac 上安装失败？

最常见原因是 npm 权限问题、Python 版本过低、端口被占用，或者浏览器控制所需依赖没有安装完整。

怎么确认 OpenClaw 已经正确安装？

检查 CLI 版本，跑完初始化流程，启动 gateway，再通过 openclaw gateway status 确认服务健康运行。

OpenClaw完整安装指南：从零到一在Mac上部署

安装成功检查清单

确认 openclaw --version 能正常返回版本号。
确认初始化流程跑完后没有依赖缺失或鉴权报错。
确认 openclaw gateway status 显示服务健康运行。
确认你能打开本地界面，或至少完成一次真实工具动作。

首次启动后还要补验什么

如果安装步骤本身已经跑完，但你还是用不起来 OpenClaw，很多时候缺的不是重装，而是安装后的最小验收。建议立刻补这四步：

运行 openclaw gateway status，确认 gateway 不是卡在 starting 或反复重启。
真正打开一次本地界面，或者完成一次简单文件读取、browser 打开这类真实动作。
确认模型或 provider 凭证已经配置好，避免把“安装成功但未鉴权”误判成“安装失败”。
如果工具调用失败，先区分是本地权限、缺凭证，还是外网可达性问题，再决定是否回头改安装步骤。

这个区分很关键，因为很多看起来像“没装好”的问题，真实根因其实在鉴权、策略或连通性，而不在安装本身。

引言

OpenClaw是一个功能强大的AI助手平台，它允许你在本地环境中部署和管理智能助手，支持浏览器控制、文件操作、消息发送等多种功能。无论你是AI爱好者、开发者还是普通用户，OpenClaw都能为你提供个性化的AI助手体验。

为什么选择OpenClaw？

本地部署：数据安全，隐私保护
多模型支持：兼容OpenAI、Anthropic等多种AI模型
丰富的工具集：浏览器控制、文件操作、消息发送等
可扩展架构：支持自定义技能和插件
跨平台：支持macOS、Linux、Windows

目标读者

本文面向Mac用户，特别是：

AI技术初学者
希望搭建本地AI助手的开发者
对隐私保护有要求的用户
想要探索AI助手功能的爱好者

准备工作

系统要求

操作系统：macOS 10.15 (Catalina) 或更高版本
内存：至少8GB RAM（推荐16GB）
存储空间：至少2GB可用空间
网络连接：用于下载依赖和访问AI模型API

必要软件

在开始安装OpenClaw之前，请确保已安装以下软件：

Homebrew（macOS包管理器）
Node.js（JavaScript运行时）
Python 3.10+（Python环境）
Git（版本控制工具）

安装步骤

步骤1：安装Homebrew

如果你还没有安装Homebrew，请打开终端并运行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，运行以下命令确保Homebrew正常工作：

brew doctor

截图示例：

终端窗口显示：
==> This script will install:
/usr/local/bin/brew
/usr/local/share/doc/homebrew...
==> The following新目录将被创建：
/usr/local/bin
/usr/local/etc
...
==> 安装成功！

步骤2：安装Node.js和npm

使用Homebrew安装Node.js：

brew install node

验证安装：

node --version
npm --version

预期输出：

node版本：v18.x.x 或更高
npm版本：9.x.x 或更高

步骤3：安装Python 3.10+

OpenClaw需要Python 3.10或更高版本：

brew install [email protected]

将Python 3.10添加到PATH：

echo 'export PATH="/usr/local/opt/[email protected]/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证Python版本：

python3 --version

预期输出：Python 3.10.x

步骤4：安装OpenClaw

方法一：使用npm安装（推荐）

npm install -g @openclaw/cli

方法二：使用pnpm安装

如果你使用pnpm：

pnpm add -g @openclaw/cli

方法三：从源码安装

# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
npm install

# 构建项目
npm run build

# 全局安装
npm link

步骤5：验证安装

安装完成后，验证OpenClaw是否正确安装：

openclaw --version

预期输出：

OpenClaw CLI v2026.2.1

如果看到版本信息，说明安装成功！

如果你装完后卡在两类高频问题，别在环境层反复兜圈：

CLI 在 hooks 加载后额外卡 20 到 40 秒，先看 CLI 回归卡顿排障页；
Codex OAuth 明明登录成功，但实际请求仍落到错误 provider 或顺序不生效，先看 Codex OAuth 排障页；
如果你暂时还分不清是安装问题、运行时问题还是 provider 配置问题，先从 OpenClaw Agents 故障总表进入。

初始配置

步骤1：运行初始化向导

首次运行OpenClaw时，需要执行初始化配置：

openclaw init

截图示例：

终端窗口显示：
◇  Welcome to OpenClaw! Let's get you set up.
│
◇  Checking system requirements...
✓  Node.js v18.17.0 detected
✓  Python 3.10.12 detected
✓  Git detected
│
◇  Creating workspace directory...
✓  Workspace created at /Users/me/.openclaw
│
◇  Configuring AI models...
? Select primary AI model provider: (Use arrow keys)
❯ OpenAI
  Anthropic
  Local (Ollama)
  Custom

步骤2：配置AI模型

根据提示选择AI模型提供商并配置API密钥：

# 如果你选择OpenAI
? Enter your OpenAI API key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
? Select default model: gpt-4-turbo

# 如果你选择DeepSeek（免费替代）
? Enter your DeepSeek API key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
? Select default model: deepseek-chat

步骤3：配置网关

OpenClaw需要一个本地网关来运行：

? Enable local gateway? (Y/n) Y
? Gateway port: 18789
? Bind to local network? (y/N) N

步骤4：完成配置

配置完成后，系统会显示摘要：

◇  Configuration Summary
│
✓  Workspace: /Users/me/.openclaw
✓  Primary model: openai/deepseek-chat
✓  Gateway: http://localhost:18789
✓  Browser control: Enabled
✓  File access: Enabled
│
◇  Running health check...
✓  All systems ready!

启动OpenClaw

启动网关服务

openclaw gateway start

预期输出：

✓  Gateway started on http://localhost:18789
✓  PID: 12345
✓  Logs: /Users/me/.openclaw/logs/gateway.log

检查服务状态

openclaw gateway status

预期输出：

✓  Gateway is running (PID: 12345)
✓  Uptime: 2 minutes
✓  URL: http://localhost:18789
✓  Connections: 0 active

停止网关服务

openclaw gateway stop

使用OpenClaw

基本命令

查看帮助：
```
openclaw --help
```
运行健康检查：
```
openclaw doctor
```
更新OpenClaw：
```
openclaw update
```

启动Web界面

OpenClaw提供了一个Web控制界面：

openclaw web

然后在浏览器中打开：http://localhost:18789

截图示例：

浏览器窗口显示OpenClaw控制面板：
左侧菜单：会话、工具、设置、日志
主区域：聊天界面，可以输入消息与AI助手对话
右侧面板：工具状态、系统信息

与AI助手对话

在终端中直接与AI助手交互：

openclaw chat

或者通过Web界面进行对话。

常见问题与解决方案

问题1：安装时出现权限错误

错误信息：

Error: EACCES: permission denied

解决方案：

# 使用sudo安装
sudo npm install -g @openclaw/cli

# 或者修复npm权限
sudo chown -R $USER /usr/local/lib/node_modules

问题2：Python版本不兼容

错误信息：

Error: Python 3.10+ is required

解决方案：

# 检查当前Python版本
python3 --version

# 如果版本低于3.10，安装正确版本
brew install [email protected]

# 创建符号链接
ln -sf /usr/local/opt/[email protected]/bin/python3 /usr/local/bin/python3

问题3：网关启动失败

错误信息：

Error: Port 18789 is already in use

解决方案：

# 查找占用端口的进程
lsof -i :18789

# 终止占用进程
kill -9 <PID>

# 或者使用其他端口
openclaw gateway start --port 18790

问题4：API密钥错误

错误信息：

Error: Invalid API key

解决方案：

# 重新配置API密钥
openclaw configure --section models

# 或者手动编辑配置文件
nano ~/.openclaw/openclaw.json

问题5：浏览器控制无法工作

错误信息：

Browser control service not available

解决方案：

# 安装Playwright浏览器
npx playwright install chromium

# 重启网关服务
openclaw gateway restart

高级配置

自定义模型配置

编辑配置文件 ~/.openclaw/openclaw.json：

{
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "your-api-key-here",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "contextWindow": 200000
          }
        ]
      }
    }
  }
}

配置多个AI模型

openclaw configure --section models

按照提示添加多个模型提供商。

设置代理（如果需要）

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
openclaw gateway start

安全注意事项

1. API密钥保护

不要将API密钥提交到版本控制系统
使用环境变量存储敏感信息
定期轮换API密钥

2. 网络访问控制

仅在需要时绑定到局域网
使用防火墙限制访问
启用身份验证

3. 文件权限

限制OpenClaw的文件访问范围
定期审查日志文件
使用最小权限原则

性能优化

1. 内存优化

# 调整Node.js内存限制
export NODE_OPTIONS="--max-old-space-size=4096"
openclaw gateway start

2. 缓存配置

# 启用模型响应缓存
openclaw configure --set cache.enabled=true

3. 日志管理

# 设置日志级别
openclaw configure --set logs.level=info

# 自动清理旧日志
openclaw configure --set logs.retentionDays=7

故障排除

诊断工具

运行完整诊断：
```
openclaw doctor --verbose
```
查看日志：
```
tail -f ~/.openclaw/logs/gateway.log
```
重置配置：
```
openclaw reset --config
```

常见错误代码

错误代码	含义	解决方案
EACCES	权限不足	检查文件权限
EADDRINUSE	端口被占用	更换端口或终止进程
ECONNREFUSED	连接被拒绝	检查服务状态
ETIMEDOUT	连接超时	检查网络连接

谁应该优先看完整安装指南

如果你属于下面这些情况，这一页更适合作为入口：

你第一次在 Mac 上安装 OpenClaw，希望一次把依赖检查齐
你预期安装阶段会遇到卡点，想把安装步骤和排障放在同一篇里看
你需要一起确认 Homebrew、Node.js、Python、浏览器依赖和 gateway 启动
你正在比较“快速安装”与“完整部署”两条路径，想先走更稳的一条

如果你已经有现成的 Node、Python、浏览器依赖，而且 gateway 也能正常启动，那么更短的 quick install 路径通常会更省时间。

常见安装判断问题

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

当你是在一台全新的 Mac 上安装、要交给不太熟悉环境的同事复现，或者你想提前规避依赖缺失时，更适合走完整安装指南。因为这类场景里，花时间把 Python、浏览器、端口和 API Key 一次检查完，通常比后面补坑更快。

什么时候安装失败更像是依赖问题，而不是 OpenClaw 本身的问题

如果 CLI 已经装上，但 openclaw gateway start 起不来，或者浏览器控制不可用，优先把它当成环境问题排查。在 Mac 上，更常见的真实阻塞是 Homebrew、Python、Playwright 浏览器依赖、权限或端口冲突，而不是 OpenClaw 包本身坏了。

安装完成后，先跑一条最小闭环任务

OpenClaw 能启动不代表已经适合接真实任务。安装后建议先跑一条最小闭环，把“命令可用、模型可用、工具可用、结果能回传”一次性确认掉：

执行一次只读状态检查，确认 Gateway、agent session 和默认模型都能返回；
让 agent 读取一个无敏感信息的本地文件或公开网页，验证工具权限边界没有被误配；
再跑一条短任务并保存 session id，确认失败时可以追溯日志和 transcript。

这一步适合承接“OpenClaw install success but agent not working”“OpenClaw 安装后怎么验证”这类搜索。它比直接接入生产账号更安全，也能更早发现模型凭据、沙箱权限或浏览器接管问题。

总结

通过本指南，你已经成功在Mac上安装了OpenClaw AI助手平台。让我们回顾一下关键步骤：

安装成果

✅ 安装了必要的依赖（Homebrew、Node.js、Python）
✅ 成功安装OpenClaw CLI工具
✅ 完成初始配置和AI模型设置
✅ 启动并运行了本地网关服务
✅ 验证了系统功能完整性

下一步建议

探索功能：
- 尝试浏览器控制功能
- 测试文件操作能力
- 体验消息发送功能
深入学习：
- 阅读官方文档：https://docs.openclaw.ai
- 加入社区讨论
- 探索自定义技能开发
优化配置：
- 根据使用习惯调整设置
- 配置多个AI模型备用
- 设置自动化任务

获取帮助

官方文档：https://docs.openclaw.ai
GitHub仓库：https://github.com/openclaw/openclaw
社区支持：Discord或论坛

更新维护

定期更新OpenClaw以获取最新功能和安全修复：

# 检查更新
openclaw update --check

# 执行更新
openclaw update

恭喜你！现在你已经拥有了一个功能完整的本地AI助手平台。OpenClaw将为你提供强大的AI助手体验，同时确保你的数据隐私和安全。开始你的AI助手之旅吧！

SEO关键词：OpenClaw安装指南，Mac AI助手部署，本地AI助手搭建，OpenClaw教程，AI助手配置，隐私保护AI，DeepSeek集成，浏览器自动化，文件操作AI，消息发送助手

相关标签：#OpenClaw #AI助手 #Mac安装 #本地部署 #隐私保护 #自动化 #浏览器控制 #AI教程

首次装好后，最容易漏掉的验收动作

很多“安装完还是不能用”的搜索词，真实问题并不在安装步骤本身，而在安装后的第一轮验收没做完整。最少补这 4 个动作：

跑一次 openclaw --version，确认 CLI 不只是装上了，而且当前 shell 能直接找到它。
跑一次 openclaw gateway status，确认 gateway 不是卡在 starting、反复重启，或者其实根本没起来。
真正执行一次最小真实动作，比如打开本地界面、读取一个文件，或者跑一个最简单的 browser 打开页动作。
检查模型或 provider 凭证是否已经配置完成，避免把“装好了但没鉴权”误判成“安装失败”。

这一步对搜索入口很关键，因为很多用户搜“OpenClaw 安装失败”“Mac 安装后打不开”“gateway 启动了但不能用”，本质上是在找安装后验收，而不只是安装命令本身。

FAQ：装好了 CLI，但还是用不起来，先判断哪一层

`openclaw --version` 正常，但 `openclaw gateway start` 或 `openclaw gateway status` 不正常，优先怀疑什么

优先怀疑本地环境层，而不是先怀疑 OpenClaw 安装包本身。Mac 上更常见的是端口冲突、Python 版本不符、浏览器依赖没补齐，或者之前残留的 gateway 进程状态异常。换句话说，这类现象更像“装好了但运行条件没满足”，而不是“根本没装上”。

gateway 已经起来了，但界面打不开或真实工具动作失败，下一跳该看哪里

先把问题从“安装”切到“连通性 / 权限 / 鉴权”这三类。比如本地界面地址是不是对、浏览器控制权限有没有给、模型 API Key 或自定义 provider 凭证是不是缺失。到这一步，如果还继续反复重装，通常只会浪费时间。

哪些现象说明你应该从完整安装指南跳去专门排障页

如果你已经确认 CLI 在、gateway 也能启动，但日志里出现反复报错、工具调用失败、browser 卡住、模型请求报鉴权或 provider 错误，这时就不该继续停留在安装页，而应该直接转去更细的故障排查页。因为真实问题已经从“安装链路”切换到了“运行链路”。

安装成功检查清单

首次启动后还要补验什么

引言

为什么选择OpenClaw？

目标读者

准备工作

系统要求

必要软件

安装步骤

步骤1：安装Homebrew

步骤2：安装Node.js和npm

步骤3：安装Python 3.10+

步骤4：安装OpenClaw

方法一：使用npm安装（推荐）

方法二：使用pnpm安装

方法三：从源码安装

步骤5：验证安装

初始配置

步骤1：运行初始化向导

步骤2：配置AI模型

步骤3：配置网关

步骤4：完成配置

启动OpenClaw

启动网关服务

检查服务状态

停止网关服务

使用OpenClaw

基本命令

启动Web界面

与AI助手对话

常见问题与解决方案

问题1：安装时出现权限错误

问题2：Python版本不兼容

问题3：网关启动失败

问题4：API密钥错误

问题5：浏览器控制无法工作

高级配置

自定义模型配置

配置多个AI模型

设置代理（如果需要）

安全注意事项

1. API密钥保护

2. 网络访问控制

3. 文件权限

性能优化

1. 内存优化

2. 缓存配置

3. 日志管理

故障排除

诊断工具

常见错误代码

谁应该优先看完整安装指南

常见安装判断问题

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

什么时候安装失败更像是依赖问题，而不是 OpenClaw 本身的问题

安装完成后，先跑一条最小闭环任务

相关阅读

总结

安装成果

下一步建议

获取帮助

更新维护

首次装好后，最容易漏掉的验收动作

FAQ：装好了 CLI，但还是用不起来，先判断哪一层

openclaw --version 正常，但 openclaw gateway start 或 openclaw gateway status 不正常，优先怀疑什么

gateway 已经起来了，但界面打不开或真实工具动作失败，下一跳该看哪里

哪些现象说明你应该从完整安装指南跳去专门排障页

常见问题

怎么在 Mac 上安装 OpenClaw？

安装 OpenClaw 前需要准备什么？

为什么 OpenClaw 在 Mac 上安装失败？

怎么确认 OpenClaw 已经正确安装？

`openclaw --version` 正常，但 `openclaw gateway start` 或 `openclaw gateway status` 不正常，优先怀疑什么