
# **引言：为什么选择在 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、编译器等。


1. 打开 **终端 **(Terminal)。

2. 输入以下命令并回车：```
	xcode-select --install
	```

3. 在弹出的窗口中点击 “Install”。等待安装完成。

4. 验证安装：输入 `git --version` 和 `gcc --version`，如果能看到版本号，则说明安装成功。


### **1.2.2 安装 Homebrew**


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


1. 在 **终端** 中，粘贴并运行以下命令（来自 [Homebrew 官网](https://brew.sh/)）：```
	/bin/bash -c "$(curl -fsSL https https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
	```

2. 安装过程中会提示您输入密码（输入时不会显示字符，输完直接回车即可）。

3. 安装完成后，根据提示，将 Homebrew 添加到您的 shell 配置文件中。对于大多数用户（使用 zsh），执行：```
	echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
	source ~/.zprofile
	```

4. 验证安装：输入 `brew --version`，如果能看到版本号，则说明安装成功。


### **1.2.3 安装 Python 3.10+**


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


1. 在 **终端** 中，运行：```
	brew install python@3.11
	```
	（我们选择 3.11 版本，它稳定且兼容性好）

2. 安装完成后，Homebrew 会提示您如何将新安装的 Python 设为默认。通常，您需要将 `/opt/homebrew/bin` 添加到 PATH 的前面。这一步在安装 Homebrew 时应该已经完成了。

3. 验证安装：关闭并重新打开终端，然后输入：```
	which python3
	python3 --version
	pip3 --version
	```
	如果 `which python3` 返回 `/opt/homebrew/bin/python3`，并且版本号正确，则说明配置成功。


### **1.2.4 (可选但推荐) 安装 Ollama**


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


1. 访问 [Ollama 官网](https://ollama.com/)。

2. 点击 “Download” 按钮，下载 `.dmg` 文件。

3. 双击 `.dmg` 文件，将 `Ollama` 应用拖拽到 `Applications` 文件夹中。

4. 首次启动 Ollama 时，系统可能会提示“无法验证开发者”，请前往 **系统设置 -> 隐私与安全性**，点击“仍要打开”。

5. Ollama 启动后会在菜单栏显示一个图标，并在后台运行。您可以通过终端命令 `ollama list` 来验证它是否正常工作。


----

# **第二章：获取与配置 OpenClaw**


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

## **2.1 克隆 OpenClaw 仓库**


1. 打开 **终端**。

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

3.  OpenClaw 的官方：```
	[OpenClaw — Personal AI Assistant](https://openclaw.ai/)
	```

4. 进入项目目录：```
	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`，然后根据自己的需求进行修改。


1. 复制文件：```
	cp .env.example .env
	```

2. 用 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**


如果项目包含前端界面：


1. 进入 `frontend` 目录：```
	cd frontend
	```

2. 安装前端依赖（需要先安装 Node.js。可通过 `brew install node` 安装）：```
	npm install
	```

3. 启动前端开发服务器：```
	npm run dev
	```

4. 打开浏览器，访问 `http://localhost:3000`，您应该能看到 OpenClaw 的聊天界面。


## **3.4 基础功能测试**


1. **API 测试**：打开浏览器，访问 `http://localhost:8000/docs`。这是自动生成的 API 文档（Swagger UI）。您可以在这里直接测试 `/chat`、`/upload` 等接口。

2. **Web UI 测试**：在 Web UI 中，尝试上传一个 PDF 或 TXT 文件，然后向机器人提问关于该文件内容的问题。观察它是否能正确回答。


**排错指南**（Mac 常见问题）


- **`ModuleNotFoundError`**：确保您是在 `(venv)` 虚拟环境中运行服务。

- **Ollama 连接被拒绝**：确保 Ollama 应用正在后台运行（检查菜单栏图标）。

- **中文模型加载慢**：首次加载 `bge-small-zh-v1.5` 可能需要几分钟，请耐心等待。


----

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


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

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


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


1. 访问 [飞书开放平台](https://open.feishu.cn/app)，创建企业自建应用。

2. 开启机器人功能。

3. **关键**：在 “事件订阅” 中，开启订阅，并记下 **验证令牌 **(Verification Token) 和 **加密密钥 **(Encrypt Key)。


## **4.2 配置内网穿透 **(Ngrok)


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


1. 访问 [Ngrok 官网](https://ngrok.com/)，注册账号。

2. 通过 Homebrew 安装 Ngrok：```
	brew install ngrok/ngrok/ngrok
	```

3. 按照官网指引，配置 AuthToken：```
	ngrok config add-authtoken <your_auth_token>
	```

4. 启动隧道：```
	ngrok http 8000
	```

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


## **4.3 修改 OpenClaw 以支持飞书 Webhook**


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


1. 在 `.env` 文件中添加飞书配置：```
	FEISHU_VERIFY_TOKEN=your_token_here
	FEISHU_ENCRYPT_KEY=your_key_here
	```

2. 编写或集成飞书 Webhook 处理代码（参考 Windows 教程中的代码片段）。

3. 实现 `send_message_to_feishu` 函数，用于调用飞书 API 发送消息。


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


----

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

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

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

人工智能

开发工具

后端

想在Mac上部署OpenClaw私有知识库？本指南详解利用M系列芯片的强大算力，通过Ollama和Metal加速，实现本地化AI问答系统。从环境配置、模型部署到飞书集成，手把手教你避开常见坑点，打造高效、安全的企业智能助手。

向量数据库

命令行工具

包管理器

数据隐私

云服务器

服务器

数据库

编译器

Windows

路由

Python

Unix

2026采购季 | AI焕新·智启新局

llmsgw

tencentdb-catalog

4核4G3M云服务器 新用户低至38元/年！

lexiang

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

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

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐