macOS 安装 OpenClaw 完整指南(小白版)

⚡ 快速安装提示（M 系列芯片用户优先）

如果你使用的是 Apple Silicon M 系列芯片的 Mac（M1/M2/M3/M4），且觉得下面的安装步骤复杂，可以直接使用一键安装工具：

方案 A：AutoClaw 一键安装（推荐新手）

AutoClaw 是智谱 AI 推出的 OpenClaw 桌面版，无需任何技术背景，双击即可安装使用。

优势：

✅ 一键安装，无需配置环境
✅ 内置 50+ 技能，开箱即用
✅ 图形化界面，操作简单
✅ 预集成智谱 AI 模型（也可配置其他模型）

下载地址：https://autoclaws.org/

适用场景： 完全不懂技术、只想快速体验 OpenClaw 功能的用户

方案 B：命令行安装（本教程）

如果你希望：

🔧 完全掌握安装过程，了解每个步骤
🎯 自定义配置 AI 模型（阿里云百炼、火山引擎豆包等）
💪 学习命令行操作，提升技术能力
🔄 方便后续升级和维护

那么请继续阅读下面的详细安装教程。

📋 什么是 OpenClaw?

OpenClaw 是一个开源的个人 AI 助手，可以通过 Telegram、飞书、WhatsApp 等聊天工具与你互动，帮你完成各种自动化任务。它可以在你的 Mac 电脑上本地运行，保护你的隐私。

⚠️ 重要提醒

安全警告： OpenClaw 是实验性软件，具有较高的系统权限。建议不要在存储重要个人数据的主力电脑上安装。如果你只有一台 Mac，请确保做好数据备份。

📝 安装前准备

系统要求

操作系统： macOS 12 或更高版本（支持 Intel 和 Apple Silicon M 系列芯片）
硬盘空间：至少 2GB 可用空间
网络：稳定的互联网连接

需要准备的账号

AI 模型 API Key（必需，二选一）：

阿里云百炼（推荐，国内稳定）：访问 https://bailian.console.aliyun.com/ 注册并开通服务，免费提供千万 tokens
火山引擎豆包（字节跳动出品）：访问 https://console.volcengine.com/ark 注册并创建接入点，赠送 50 万免费 tokens

聊天平台账号（可选，安装后配置）：

飞书账号：用于创建飞书机器人，实现与 AI 助手的聊天交互

🚀 安装步骤

第一步：打开终端（Terminal）

按下键盘上的 Command (⌘) + 空格键，打开“聚焦搜索”
输入 terminal 或 终端
按回车键打开终端应用

💡 小提示： 终端是一个黑色或白色的窗口，可以通过输入命令来操作电脑。不用担心，只需要复制粘贴命令即可。

第二步：安装 Homebrew（包管理器）

Homebrew 是 macOS 上最常用的软件包管理工具，可以帮助我们轻松安装各种软件。

检查是否已安装

在终端中输入以下命令，然后按回车：

brew --version

如果显示版本号（如 Homebrew 4.x.x），说明已安装，跳过此步骤
如果显示 command not found，需要安装 Homebrew

安装 Homebrew

方案一：使用国内镜像安装（推荐，速度快）

复制以下命令，粘贴到终端，按回车：

/bin/bash -c "$(curl -fsSL https://gitee.com/ineo6/homebrew-install/raw/master/install.sh)"

方案二：使用官方源安装（需要稳定的国际网络）

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

安装过程中可能需要：

输入你的 Mac 登录密码（输入时不会显示任何字符，这是正常的）
等待 5-10 分钟（取决于网络速度）

安装完成后配置国内镜像源（重要）：

# 配置 Homebrew 国内镜像
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"
# 将配置写入配置文件（永久生效）
echo'export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"' >> ~/.zshrc
echo'export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"' >> ~/.zshrc
echo'export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"' >> ~/.zshrc
echo'export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"' >> ~/.zshrc
# 使配置生效
source ~/.zshrc

💡 小提示： 配置镜像源后，后续使用 Homebrew 安装软件会自动使用清华大学镜像，速度更快。

第三步：安装 Node.js

Node.js 是 OpenClaw 运行所需的基础环境。

使用 Homebrew 安装 Node.js

brew install node@24

验证安装

node --version
npm --version

如果显示版本号（如 v24.x.x 和 10.x.x），说明安装成功。

第四步：配置 npm 国内镜像源（重要）

为了提高下载速度，我们需要配置 npm 使用国内镜像源。

配置淘宝镜像（推荐）

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com
# 验证配置
npm config get registry

预期输出：https://registry.npmmirror.com/

其他可选镜像源

如果淘宝镜像速度不理想，可以尝试以下镜像：

腾讯云镜像：

npm config set registry https://mirrors.cloud.tencent.com/npm/

华为云镜像：

npm config set registry https://repo.huaweicloud.com/repository/npm/

阿里云镜像：

npm config set registry https://registry.npmmirror.com

💡 小提示： 配置镜像源后，后续安装 npm 包的速度会大幅提升，无需每次都指定镜像。

第五步：安装 OpenClaw

全局安装 OpenClaw

由于已经配置了 npm 国内镜像，直接执行以下命令即可快速安装：

sudo npm install -g openclaw@latest

安装过程：

输入你的 Mac 登录密码（输入时不显示）
等待 5-10 分钟，安装过程中会下载很多依赖包
由于使用了国内镜像，下载速度会比较快

可能遇到的问题

问题 1：sharp 模块安装失败

如果看到 sharp: Please add node-gyp to your dependencies 错误，执行：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

问题 2：网络超时或下载缓慢

如果遇到网络问题，可以尝试切换其他镜像源：

# 切换到腾讯云镜像
npm config set registry https://mirrors.cloud.tencent.com/npm/
# 重新安装
sudo npm install -g openclaw@latest

问题 3：权限问题

如果提示权限不足，确保使用了 sudo 命令：

sudo npm install -g openclaw@latest

验证安装

openclaw --version

预期输出： 显示版本号（如 0.9.x），说明安装成功！

💡 小提示： 如果安装过程中遇到任何问题，可以先尝试清除 npm 缓存：

npm cache clean --force

然后重新安装。

第六步：配置 OpenClaw（重要）

现在开始配置 OpenClaw，这一步会设置 AI 模型和聊天平台。

运行配置向导：

openclaw onboard --install-daemon

参数说明：--install-daemon 会将 OpenClaw 安装为后台服务，开机自动启动。

配置步骤详解

配置向导会依次询问以下问题，请按照提示操作：

① 选择 AI 模型提供商

提示信息：

? Which AI provider would you like to use?

操作： 使用方向键选择 Other / Custom（自定义提供商），按回车

然后根据你选择的平台输入相应信息：

🔹 方案一：阿里云百炼（推荐新手）

配置项	输入内容
Provider name	`bailian`
API Base URL	`https://dashscope.aliyuncs.com/compatible-mode/v1`
API Key	粘贴你的阿里云百炼 API Key（格式：`sk-xxxxx`）
Model name	`qwen-plus` 或 `qwen-max`（推荐 `qwen-plus`）

优势： OpenAI 兼容接口，配置简单，免费千万 tokens

🔹 方案二：火山引擎豆包

配置项	输入内容
Provider name	`doubao`
API Base URL	`https://ark.cn-beijing.volces.com/api/v3`
API Key	粘贴你的火山引擎 API Key
Model name	`doubao-pro-32k` 或你的接入点 ID（如 `ep-xxxxx`）

注意： 需要先在火山引擎控制台创建“推理接入点”，然后使用接入点 ID 作为模型名称

② 配置聊天平台（可选）

提示信息：

? Which messaging platform would you like to connect?

建议选择：

Feishu（飞书） - 适合国内用户，功能强大，支持群聊协作
No / Skip（跳过） - 稍后在控制面板中配置（推荐新手选择）

💡 小提示： 建议先跳过此步骤，完成基础安装后再配置飞书，这样可以先验证 OpenClaw 是否正常运行。

③ 是否安装 Skills（技能）

提示信息：

? Would you like to install skills now?

建议选择：No（稍后在控制面板中安装更方便）

④ 完成配置

看到以下信息表示配置完成：

✓ Installation finished successfully!

第七步：启动 OpenClaw

1. 启动网关服务：

openclaw gateway start

2. 打开控制面板：

openclaw dashboard

这会自动在浏览器中打开 OpenClaw 的控制面板（通常是 http://localhost:18789）

🎯 验证安装

检查服务状态

openclaw status

预期输出： 应该显示 Gateway is running

检查系统配置

openclaw doctor

作用： 检查配置文件是否有问题，如有错误会给出提示

🔧 常见问题解决

问题 1：`command not found: openclaw`

原因： npm 全局安装路径不在系统 PATH 中。

解决方法：

查看 npm 全局安装路径：bash npm prefix -g
将路径添加到 PATH（假设路径是 /usr/local）：bash echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
重新打开终端，再次尝试 openclaw --version

问题 2：端口 18789 被占用

解决方法：

查看占用端口的进程：bash lsof -i :18789

杀死占用的进程或修改 OpenClaw 端口：bash openclaw gateway start --port 18790

问题 3：配置文件格式错误

解决方法：

打开配置文件：bash open ~/.openclaw/openclaw.json

检查是否有：

全角字符（如中文逗号、引号）
多余的逗号
缺少引号

或者直接重新运行配置向导：bash openclaw onboard

问题 4：调整模型上下文窗口大小

解决方法：

编辑配置文件：

open ~/.openclaw/openclaw.json

找到你的 AI 模型配置部分（如 bailian 或 doubao），修改：

"contextWindow":32000,
"maxTokens":8000

小提示：

阿里云百炼 qwen-plus 支持最大 32k 上下文
火山引擎豆包 doubao-pro-32k 支持最大 32k 上下文
根据实际需求调整，上下文越大消耗 tokens 越多

保存后重启服务：

openclaw gateway restart

📱 配置聊天平台（可选）

配置飞书机器人（推荐国内用户）

飞书是国内最适合与 OpenClaw 集成的聊天平台，支持私聊、群聊、文件传输等丰富功能。

第一步：创建飞书自建应用

访问飞书开放平台
小提示： 如果使用国际版 Lark，访问 https://open.larksuite.com/app

打开浏览器，访问：https://open.feishu.cn/app
使用你的飞书账号登录

创建企业自建应用

应用名称： 例如 “OpenClaw AI 助手”
应用描述： 例如 “我的个人 AI 助手”
应用图标： 上传一个机器人图标（可选）

点击右上角 “创建企业自建应用” 按钮
填写应用信息：
点击 “创建” 完成

获取应用凭证
⚠️ 安全提醒： App Secret 是敏感信息，不要分享给他人或上传到网上。

App ID（格式：cli_xxxxxxxxxx）
App Secret（点击“查看”按钮显示，格式：一长串字符）

创建完成后，进入应用管理页面
点击左侧菜单 “凭证与基础信息”
找到并复制以下两个重要信息（务必保存好）：

第二步：配置机器人权限

批量导入权限（推荐方法）

点击左侧菜单 “权限管理”，然后点击 “批量导入” 按钮，复制以下 JSON 配置并粘贴：

{
"scopes":{
"tenant":[
"im:message",
"im:message:readonly",
"im:message:send_as_bot",
"im:message.p2p_msg:readonly",
"im:message.group_at_msg:readonly",
"im:chat.access_event.bot_p2p_chat:read",
"im:chat.members:bot_access",
"im:resource",
"contact:user.employee_id:readonly"
],
"user":[
"im:chat.access_event.bot_p2p_chat:read"
]
}
}

点击 “确认” 完成权限导入。

手动添加权限（备选方法）
如果批量导入不可用，在“权限管理”页面搜索并勾选以下权限：

✅ 获取与发送单聊、群组消息
✅ 接收消息 v2.0
✅ 获取群组信息
✅ 以应用身份发消息
✅ 获取用户 ID

发布应用版本

点击左侧菜单 “版本管理与发布”
点击 “创建版本”
填写版本说明（如 “初始版本”）
选择 “仅企业内部可用”
点击 “保存” 并 “申请发布”
等待管理员审核通过（如果你是管理员，直接通过即可）

第三步：在 OpenClaw 中添加飞书频道

运行添加频道命令
在终端中执行：
```
openclaw channels add
```
按照提示配置
```
? Which channel would you like to add?
```
使用方向键选择 Feishu（飞书），按回车
```
? Enter Feishu App ID:
```
粘贴第一步中复制的 App ID，按回车
```
? Enter Feishu App Secret:
```
粘贴第一步中复制的 App Secret，按回车
看到 ✓ Feishu channel added successfully 表示添加成功。
重启 OpenClaw 网关
```
openclaw gateway restart
```

第四步：添加机器人到飞书

在飞书中搜索机器人

打开飞书客户端（手机或电脑）
点击顶部搜索框
输入你创建的应用名称（如 “OpenClaw AI 助手”）
点击搜索结果中的机器人

发送测试消息

向机器人发送任意消息，例如：“你好”
机器人会回复一个 配对码（格式：YXXX）

批准配对请求
回到终端，执行以下命令（将 RYXBPRNJ 替换为你收到的实际配对码）：
```
openclaw pairing approve feishu RYXBPRNJ
```
看到 ✓ Pairing approved 表示配对成功。
测试对话

回到飞书，再次向机器人发送消息：“你好，请介绍一下你自己”
如果机器人正常回复，说明配置成功！🎉

第五步：在群聊中使用机器人（可选）

添加机器人到群聊

打开飞书群聊
点击右上角 “…” → “设置”
选择 “群机器人” → “添加机器人”
搜索并添加你的 OpenClaw 机器人

在群聊中 @ 机器人

在群聊中输入 @OpenClaw AI 助手 （你的机器人名称）
输入你的问题或指令
机器人会在群聊中回复

常见问题

问题 1：机器人不回复消息

解决方法：

检查 Gateway 是否运行：openclaw status
查看日志：openclaw logs --follow
确认权限配置正确，特别是消息相关权限
重启网关：openclaw gateway restart

问题 2：配对码过期

解决方法：

配对码有效期较短，如果过期，重新向机器人发送消息获取新的配对码
收到配对码后尽快执行 openclaw pairing approve 命令

问题 3：群聊中机器人无响应

解决方法：

确保在群聊中 @ 提及机器人，否则机器人不会响应
检查机器人是否有群消息权限（im: message.group_at_msg: readonly）
查看日志确认是否收到群消息：openclaw logs --follow

问题 4：使用国际版 Lark

解决方法：

如果使用 Lark（国际版），需要修改配置文件：

open ~/.openclaw/openclaw.json

找到 feishu 配置部分，添加 "domain": "lark"：

{
"channels":{
"feishu":{
"enabled":true,
"domain":"lark",
"accounts":{
"main":{
"appId":"cli_xxx",
"appSecret":"xxx"
}
}
}
}
}

保存后重启网关：openclaw gateway restart

高级功能：快速批量授权

如果希望 OpenClaw 能够操作你的飞书文档、日历、多维表格等，可以在飞书对话中发送：

/feishu auth

按照提示完成授权，OpenClaw 将获得更强大的自动化能力。

配置 Telegram Bot（国际用户推荐）

在 Telegram 中搜索 @BotFather
发送 /newbot 创建新机器人
按提示设置机器人名称和用户名
复制获得的 Bot Token
执行 openclaw channels add，选择 Telegram，粘贴 Token
重启网关：openclaw gateway restart
在 Telegram 中搜索你的机器人，发送消息测试

🎓 开始使用

基本命令

`bash 启动服务 openclaw gateway start

停止服务 openclaw gateway stop

重启服务 openclaw gateway restart

查看状态 openclaw status

打开控制面板 openclaw dashboard

查看日志 openclaw logs

系统诊断 openclaw doctor`

安装 Skills（技能）

打开控制面板：openclaw dashboard
点击左侧菜单的 “Skills”
浏览并安装你需要的技能
通过聊天平台向 OpenClaw 发送指令测试

🔄 更新 OpenClaw

bash sudo npm update -g openclaw @latest

🗑️ 卸载 OpenClaw

如果需要完全卸载：

`bash 停止服务 openclaw gateway stop

卸载全局包 sudo npm uninstall -g openclaw

删除配置文件 rm -rf ~/.openclaw

删除系统服务（如果安装了）launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plistrm ~/Library/LaunchAgents/com.openclaw.gateway.plist`

📚 参考资源

OpenClaw 官方文档
OpenClaw GitHub 仓库
阿里云百炼控制台
火山引擎方舟平台

💡 小贴士

首次使用建议： 推荐使用阿里云百炼，免费赠送千万 tokens，配置简单，国内访问稳定
安全建议： 不要在 OpenClaw 中处理敏感信息，它会将数据发送给 AI 模型
性能优化： 如果 Mac 配置较低，可以考虑关闭一些不常用的 Skills
定期更新： OpenClaw 更新频繁，建议每月检查更新
模型选择： 阿里云百炼的 qwen-plus 性价比高，日常使用足够；火山引擎豆包响应速度快，适合实时对话

恭喜你！现在你已经成功在 Mac 上安装了 OpenClaw。开始探索 AI 助手的强大功能吧！如果遇到问题，可以查看官方文档或在社区寻求帮助。

⚡ 快速安装提示（M 系列芯片用户优先）

方案 A：AutoClaw 一键安装（推荐新手）

方案 B：命令行安装（本教程）

📋 什么是 OpenClaw?

第一步：打开终端（Terminal）

第二步：安装 Homebrew（包管理器）

检查是否已安装

安装 Homebrew

第三步：安装 Node.js

使用 Homebrew 安装 Node.js

验证安装

第四步：配置 npm 国内镜像源（重要）

配置淘宝镜像（推荐）

其他可选镜像源

第五步：安装 OpenClaw

全局安装 OpenClaw

可能遇到的问题

验证安装

第六步：配置 OpenClaw（重要）

配置步骤详解

① 选择 AI 模型提供商

② 配置聊天平台（可选）

③ 是否安装 Skills（技能）

④ 完成配置

第七步：启动 OpenClaw

🎯 验证安装

检查服务状态

检查系统配置

🔧 常见问题解决

问题 1：command not found: openclaw

配置飞书机器人（推荐国内用户）

第一步：创建飞书自建应用

第二步：配置机器人权限

第三步：在 OpenClaw 中添加飞书频道

第四步：添加机器人到飞书

第五步：在群聊中使用机器人（可选）

常见问题

高级功能：快速批量授权

配置 Telegram Bot（国际用户推荐）

问题 1：`command not found: openclaw`