OpenClaw macOS 安装与配置全攻略
想要在 macOS 系统上成功部署并运行 OpenClaw 智能助理吗？尤其是在系统权限受限或 Node.js 版本过旧的情况下，这份详尽的指南将帮助你高效完成配置，避免常见的安装陷阱。让我们立即开始。
功能展示
系统环境与前置条件
在开始安装 OpenClaw 之前，请确保你的开发环境满足以下基本要求：
操作系统: macOS（支持 Intel 和 Apple Silicon 全系列芯片）。
Node.js 版本: 强烈建议使用 v20 或 v22 的 LTS 版本，最低兼容版本为 v18。
飞书/Lark 账号: 你需要一个具备飞书开放平台应用创建和管理权限的企业账号。
第一步：配置 Node.js 运行环境
若系统预装的 Node.js 版本过低，使用包管理器升级可能遇到权限问题。推荐直接下载官方预编译的二进制包，这是一种更直接、更可控的解决方案。操作步骤如下：
- 下载 Node.js v22 二进制包：
curl -L https://nodejs.org/dist/v22.14.0/node-v22.14.0-darwin-x64.tar.gz -o node.tar.gz
tar -xzf node.tar.gz
mv node-v22.14.0-darwin-x64 nodejs- 临时添加 Node.js 到系统路径：
export PATH="$PWD/nodejs/bin:$PATH"第二步：安装 OpenClaw 命令行工具
完成 Node.js 环境配置后，即可通过 npm 包管理器全局安装 OpenClaw 的核心 CLI 工具。执行以下命令获取最新稳定版本：
npm install -g openclaw@latest第三步：初始化项目与数据目录迁移
在 macOS 系统中，默认的 OpenClaw 数据存储路径 `~/.openclaw` 可能因严格的系统沙盒或权限策略导致写入失败。一个可靠的解决方案是在当前项目根目录下创建独立的数据文件夹。
- 创建本地数据存储目录：
mkdir -p .openclaw_data- 执行非交互式初始化配置：
export OPENCLAW_CONFIG_PATH="$PWD/.openclaw_data/openclaw.json"
export OPENCLAW_STATE_DIR="$PWD/.openclaw_data"
openclaw setup --non-interactive第四步：接入 AI 大语言模型（以通义千问 Qwen 为例）
OpenClaw 的强大功能依赖于后端的大语言模型。本文以阿里云的通义千问（Qwen）为例。首先，你需要通过 CLI 工具登录你的模型服务平台账号：
openclaw models auth login --provider qwen-portal第五步：配置飞书/Lark 机器人集成
为了让 OpenClaw 能够通过飞书与企业成员交互，你需要安装官方飞书插件，并在飞书开放平台完成应用配置。
- 安装飞书官方插件：
openclaw plugins install @openclaw/feishu访问飞书开放平台，创建新的企业自建应用，并妥善保存获取到的 `App ID` 和 `App Secret` 凭证。
配置飞书频道连接：使用文本编辑器打开配置文件 `.openclaw_data/openclaw.json`，在 `channels` 配置段中添加以下飞书频道设置（请务必将示例值替换为你自己的实际凭证）：
"channels": {
"feishu": {
"enabled": true,
"appId": "你的_APP_ID",
"appSecret": "你的_APP_SECRET",
"domain": "feishu",
"dmPolicy": "open",
"allowFrom": ["*"]
}
}第六步：启动 OpenClaw 网关服务
为了简化后续的启动流程并固化环境变量，建议创建一个专用的启动脚本 `run_openclaw.sh`，内容如下：
#!/bin/bash
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
export PATH="$SCRIPT_DIR/nodejs/bin:$PATH"
export OPENCLAW_CONFIG_PATH="$SCRIPT_DIR/.openclaw_data/openclaw.json"
export OPENCLAW_STATE_DIR="$SCRIPT_DIR/.openclaw_data"
openclaw "$@"保存脚本后，为其添加可执行权限，并启动核心的 Gateway 服务：
chmod +x run_openclaw.sh
./run_openclaw.sh gateway --force核心操作命令速查手册
服务成功启动后，你可以使用以下常用命令进行管理和交互：
访问管理控制台: 在浏览器中打开 https://127.0.0.1:18789/
实时查看运行日志:
./run_openclaw.sh logs --follow批准飞书用户配对请求:
./run_openclaw.sh pairing approve feishu <配对码>查看已安装的所有技能:
./run_openclaw.sh skills list
常见 macOS 权限错误排查
若在运行过程中遇到 `EPERM: operation not permitted` 等文件系统权限错误，请按顺序检查以下两项配置：
确认环境变量 `OPENCLAW_STATE_DIR` 所指向的目录当前用户拥有完整的读取和写入权限。
检查 `openclaw.json` 配置文件中的 `agents.defaults.workspace` 和 `agents.list[0].workspace` 字段，确保其路径也指向一个本地可自由读写的目录，而非受系统保护的区域。
