Mac 本地部署 OpenClaw！完整安装教程 + 飞书接入，全程避坑——从零开始，手把手教你搭建企业级知识库问答机器人，并无缝集成飞书

yangzhihua

42人浏览 · 2026-05-07 18:41:13

yangzhihua · 2026-05-07 18:41:13 发布

引言：为什么选择在 Mac 上部署 OpenClaw？

对于开发者、研究人员和小型团队而言，MacBook Pro 或 iMac 不仅是日常工作的主力设备，其强大的 M 系列芯片（M1, M2, M3）也为本地运行 AI 模型提供了前所未有的可能性。OpenClaw 是一个基于大语言模型（LLM）和向量数据库构建的本地化、私有化知识库问答系统。

在 Mac 上部署 OpenClaw，您可以享受到：

极致的数据隐私：所有敏感的企业文档和对话记录都只存在于您的设备上。
利用 Apple Silicon 的强大算力：通过 llama.cpp 和 Metal 加速，M 系列芯片能以极高的效率运行量化后的 LLM。
无缝的开发体验：macOS 基于 Unix，拥有优秀的命令行工具和包管理器（如 Homebrew），使得环境配置比 Windows 更为顺畅。
低成本启动：无需租用昂贵的云服务器，即可拥有一个功能完备的智能助手。

本文将为您提供一份保姆级的 macOS 本地部署指南，并详细讲解如何将其接入飞书，打造一个属于您自己的、7x24小时在线的企业智能助手。我们将重点关注并规避 macOS 环境下常见的各种“坑”，确保您能一次成功。

第一章：环境准备——为 Apple Silicon 优化

在开始之前，请确保您的 Mac 满足以下要求，并完成必要的软件安装。

1.1 硬件与系统要求

操作系统：macOS Monterey (12.0) 或更高版本。建议使用最新版 macOS Sonoma 以获得最佳兼容性和性能。
芯片：**Apple Silicon **(M1/M2/M3 系列)。虽然 Intel Mac 也可以运行，但性能和能效远不如 Apple Silicon。本教程将重点围绕 Apple Silicon 进行优化。
内存（RAM） 强烈建议 16GB 或以上。32GB 是更理想的选择，尤其是在处理大型文档或运行 7B 以上参数的模型时。
存储（硬盘） 至少预留 50GB 的可用空间。SSD 是标配，速度不是问题，但空间要足够。

1.2 软件依赖安装

我们需要安装以下几个关键软件：

1.2.1 安装 Xcode Command Line Tools

这是 macOS 开发的基础工具集，包含了 Git、编译器等。

打开 **终端 **(Terminal)。
输入以下命令并回车：
```
xcode-select --install
```
在弹出的窗口中点击 “Install”。等待安装完成。
验证安装：输入 git --version 和 gcc --version，如果能看到版本号，则说明安装成功。

1.2.2 安装 Homebrew

Homebrew 是 macOS 上最流行的包管理器，可以方便地安装各种开源软件。

在终端中，粘贴并运行以下命令（来自 Homebrew 官网）：

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

安装过程中会提示您输入密码（输入时不会显示字符，输完直接回车即可）。
安装完成后，根据提示，将 Homebrew 添加到您的 shell 配置文件中。对于大多数用户（使用 zsh），执行：
```
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile
```
验证安装：输入 brew --version，如果能看到版本号，则说明安装成功。

1.2.3 安装 Python 3.10+

虽然 macOS 自带 Python，但版本通常较旧且不建议直接使用。我们将通过 Homebrew 安装一个干净的 Python 环境。

在终端中，运行：
```
brew install python@3.11
```
（我们选择 3.11 版本，它稳定且兼容性好）
安装完成后，Homebrew 会提示您如何将新安装的 Python 设为默认。通常，您需要将 /opt/homebrew/bin 添加到 PATH 的前面。这一步在安装 Homebrew 时应该已经完成了。
验证安装：关闭并重新打开终端，然后输入：
```
which python3
python3 --version
pip3 --version
```
如果 which python3 返回 /opt/homebrew/bin/python3，并且版本号正确，则说明配置成功。

1.2.4 (可选但推荐) 安装 Ollama

Ollama 是一个专门为在本地运行 LLM 而设计的工具，对 Apple Silicon 的 Metal 加速支持得非常好，使用起来极其简单。

访问 Ollama 官网。
点击 “Download” 按钮，下载 .dmg 文件。
双击 .dmg 文件，将 Ollama 应用拖拽到 Applications 文件夹中。
首次启动 Ollama 时，系统可能会提示“无法验证开发者”，请前往 系统设置 -> 隐私与安全性，点击“仍要打开”。
Ollama 启动后会在菜单栏显示一个图标，并在后台运行。您可以通过终端命令 ollama list 来验证它是否正常工作。

第二章：获取与配置 OpenClaw

现在，我们正式开始部署 OpenClaw。

2.1 克隆 OpenClaw 仓库

打开终端。
选择一个合适的目录来存放项目，例如 ~/projects。执行以下命令进入该目录：
```
mkdir -p ~/projects && cd ~/projects
```

克隆 OpenClaw 的官方仓库：

git clone https://github.com/claw-org/openclaw.git

进入项目目录：
```
cd openclaw
```

2.2 创建并激活 Python 虚拟环境

使用虚拟环境可以隔离项目依赖，避免与其他 Python 项目产生冲突。

# 创建名为 'venv' 的虚拟环境
python3 -m venv venv

# 激活虚拟环境
source venv/bin/activate

激活成功后，您会看到命令行前缀变成了 (venv)。

2.3 安装 Python 依赖

在激活的虚拟环境中，安装项目所需的所有 Python 库。

# 升级 pip 到最新版
python -m pip install --upgrade pip

# 安装项目依赖
pip install -r requirements.txt

常见坑点及解决方案（Mac 特有）

faiss 安装失败：faiss 是 Facebook 开源的向量相似度搜索库。在 Apple Silicon 上，直接通过 pip 安装预编译的 faiss-cpu 通常没有问题。但如果遇到错误，可以尝试先用 Homebrew 安装其依赖：
```
brew install swig
```
然后再运行 pip install faiss-cpu。
tokenizers 或 torch 安装缓慢：这些库很大，且默认从 PyPI 下载。可以使用国内镜像源加速：
```
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

2.4 配置 `.env` 文件

OpenClaw 使用 .env 文件来管理各种配置项。项目根目录下通常有一个 .env.example 文件，我们需要将其复制并重命名为 .env，然后根据自己的需求进行修改。

复制文件：
```
cp .env.example .env
```
用 VS Code、Sublime Text 或 nano 打开 .env 文件。

关键配置项解释（针对 Mac + Ollama 优化）

VECTOR_STORE=faiss：指定向量数据库。我们这里使用 faiss。
EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5：强烈推荐使用这个中文嵌入模型，它在中文任务上表现优异。如果您主要处理英文，可以使用 sentence-transformers/all-MiniLM-L6-v2。
LLM_MODEL_TYPE=ollama：指定 LLM 的来源。我们这里使用 ollama，因为它能完美利用 Apple Silicon 的 GPU。
OLLAMA_MODEL=qwen:7b：指定 Ollama 中要使用的具体模型。qwen（通义千问）是一个优秀的开源中文模型。您也可以选择 llama3:8b、phi3:mini 等。注意：首次使用模型时，Ollama 会自动下载，这可能需要一些时间。
UPLOAD_DIR=./uploads：指定用户上传文件的存储目录。
FAISS_PATH=./vector_store：指定 Faiss 向量数据库的持久化路径。

配置示例

VECTOR_STORE=faiss
EMBEDDING_MODEL=BAAI/bge-small-zh-v1.5
LLM_MODEL_TYPE=ollama
OLLAMA_MODEL=qwen:7b
UPLOAD_DIR=./uploads
FAISS_PATH=./vector_store

第三章：启动服务与基础测试

完成配置后，我们就可以启动 OpenClaw 服务了。

3.1 预加载模型（重要步骤）

为了确保服务启动时不会卡住，建议先手动通过 Ollama 加载您在 .env 中指定的模型。

# 在另一个终端窗口中（不要在 (venv) 环境里）
ollama run qwen:7b

Ollama 会开始下载并加载 qwen:7b 模型。您会看到进度条。加载完成后，您可以直接输入一个问题进行测试，比如 你好。测试完毕后，按 Ctrl+C 退出。模型已经被缓存，后续服务调用会非常快。

3.2 启动后端 API 服务

在激活的 (venv) 虚拟环境中，运行以下命令：

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

--host 0.0.0.0：允许局域网内的其他设备访问此服务。
--port 8000：服务监听的端口。
--reload：开启热重载，方便开发调试。

如果一切顺利，您会看到类似 Uvicorn running on http://0.0.0.0:8000 的日志输出。

3.3 (可选) 启动前端 Web UI

如果项目包含前端界面：

进入 frontend 目录：
```
cd frontend
```
安装前端依赖（需要先安装 Node.js。可通过 brew install node 安装）：
```
npm install
```
启动前端开发服务器：
```
npm run dev
```
打开浏览器，访问 http://localhost:3000，您应该能看到 OpenClaw 的聊天界面。

3.4 基础功能测试

API 测试：打开浏览器，访问 http://localhost:8000/docs。这是自动生成的 API 文档（Swagger UI）。您可以在这里直接测试 /chat、/upload 等接口。
Web UI 测试：在 Web UI 中，尝试上传一个 PDF 或 TXT 文件，然后向机器人提问关于该文件内容的问题。观察它是否能正确回答。

排错指南（Mac 常见问题）

ModuleNotFoundError：确保您是在 (venv) 虚拟环境中运行服务。
Ollama 连接被拒绝：确保 Ollama 应用正在后台运行（检查菜单栏图标）。
中文模型加载慢：首次加载 bge-small-zh-v1.5 可能需要几分钟，请耐心等待。

第四章：深度集成——将 OpenClaw 接入飞书

现在，让我们把本地部署的 OpenClaw 变成一个飞书群聊机器人。

4.1 在飞书开发者后台创建机器人

这部分操作与平台无关，与 Windows 教程相同。

访问飞书开放平台，创建企业自建应用。
开启机器人功能。
关键：在 “事件订阅” 中，开启订阅，并记下 **验证令牌 **(Verification Token) 和 **加密密钥 **(Encrypt Key)。

4.2 配置内网穿透 (Ngrok)

由于我们的服务在本地，需要让公网的飞书服务器能访问到。

访问 Ngrok 官网，注册账号。
通过 Homebrew 安装 Ngrok：
```
brew install ngrok/ngrok/ngrok
```

按照官网指引，配置 AuthToken：

ngrok config add-authtoken <your_auth_token>

启动隧道：
```
ngrok http 8000
```
将 Ngrok 提供的公网地址（如 https://xxxx.ngrok-free.app）填入飞书后台的 “请求网址”。

4.3 修改 OpenClaw 以支持飞书 Webhook

这部分代码逻辑与 Windows 教程完全一致。您需要在 FastAPI 后端增加一个处理飞书事件的路由，并实现签名验证、消息解析和回复发送的逻辑。

在 .env 文件中添加飞书配置：

FEISHU_VERIFY_TOKEN=your_token_here
FEISHU_ENCRYPT_KEY=your_key_here

编写或集成飞书 Webhook 处理代码（参考 Windows 教程中的代码片段）。
实现 send_message_to_feishu 函数，用于调用飞书 API 发送消息。

完成以上步骤后，重启您的 OpenClaw 服务。现在，在飞书群聊中 @ 您的机器人并提问，它就应该能利用您 Mac 本地的知识库给出回答了！得益于 Apple Silicon 的强大性能，响应速度会非常快。

恭喜您！您已经成功在 Mac 上部署了 OpenClaw 并将其接入飞书！充分利用了您 Mac 的强大算力，打造了一个私有、安全、高效的智能助手。如果您在操作过程中遇到任何问题，或者觉得这篇教程对您有帮助，欢迎在评论区留言交流。别忘了点赞、收藏、关注，以便获取更多 AI 和 macOS 开发相关的实战教程！