Mac本地部署OpenClaw详细步骤与操作指南

OpenClaw macOS 安装与配置全攻略

想要在 macOS 系统上成功部署并运行 OpenClaw 智能助理吗？尤其是在系统权限受限或 Node.js 版本过旧的情况下，这份详尽的指南将帮助你高效完成配置，避免常见的安装陷阱。让我们立即开始。

功能展示

系统环境与前置条件

在开始安装 OpenClaw 之前，请确保你的开发环境满足以下基本要求：

• 操作系统: macOS（支持 Intel 和 Apple Silicon 全系列芯片）。

• Node.js 版本: 强烈建议使用 v20 或 v22 的 LTS 版本，最低兼容版本为 v18。

• 飞书/Lark 账号: 你需要一个具备飞书开放平台应用创建和管理权限的企业账号。

第一步：配置 Node.js 运行环境

若系统预装的 Node.js 版本过低，使用包管理器升级可能遇到权限问题。推荐直接下载官方预编译的二进制包，这是一种更直接、更可控的解决方案。操作步骤如下：

1. 下载 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

2. 临时添加 Node.js 到系统路径：

export PATH="$PWD/nodejs/bin:$PATH"

第二步：安装 OpenClaw 命令行工具

完成 Node.js 环境配置后，即可通过 npm 包管理器全局安装 OpenClaw 的核心 CLI 工具。执行以下命令获取最新稳定版本：

npm install -g openclaw@latest

第三步：初始化项目与数据目录迁移

在 macOS 系统中，默认的 OpenClaw 数据存储路径 `~/.openclaw` 可能因严格的系统沙盒或权限策略导致写入失败。一个可靠的解决方案是在当前项目根目录下创建独立的数据文件夹。

1. 创建本地数据存储目录：

mkdir -p .openclaw_data

2. 执行非交互式初始化配置：

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 能够通过飞书与企业成员交互，你需要安装官方飞书插件，并在飞书开放平台完成应用配置。

1. 安装飞书官方插件：

openclaw plugins install @openclaw/feishu

2. 访问飞书开放平台，创建新的企业自建应用，并妥善保存获取到的 `App ID` 和 `App Secret` 凭证。

3. 配置飞书频道连接：使用文本编辑器打开配置文件 `.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

核心操作命令速查手册

服务成功启动后，你可以使用以下常用命令进行管理和交互：

• 访问管理控制台: 在浏览器中打开 http://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` 等文件系统权限错误，请按顺序检查以下两项配置：

1. 确认环境变量 `OPENCLAW_STATE_DIR` 所指向的目录当前用户拥有完整的读取和写入权限。

2. 检查 `openclaw.json` 配置文件中的 `agents.defaults.workspace` 和 `agents.list[0].workspace` 字段，确保其路径也指向一个本地可自由读写的目录，而非受系统保护的区域。