引言为什么选择在 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 安装 HomebrewHomebrew 是 macOS 上最流行的包管理器可以方便地安装各种开源软件。在终端中粘贴并运行以下命令来自 Homebrew 官网/bin/bash-c$(curl-fsSLhttps https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)安装过程中会提示您输入密码输入时不会显示字符输完直接回车即可。安装完成后根据提示将 Homebrew 添加到您的 shell 配置文件中。对于大多数用户使用 zsh执行echoeval $(/opt/homebrew/bin/brew shellenv)~/.zprofilesource~/.zprofile验证安装输入brew --version如果能看到版本号则说明安装成功。1.2.3 安装 Python 3.10虽然 macOS 自带 Python但版本通常较旧且不建议直接使用。我们将通过 Homebrew 安装一个干净的 Python 环境。在终端中运行brewinstallpython3.11我们选择 3.11 版本它稳定且兼容性好安装完成后Homebrew 会提示您如何将新安装的 Python 设为默认。通常您需要将/opt/homebrew/bin添加到 PATH 的前面。这一步在安装 Homebrew 时应该已经完成了。验证安装关闭并重新打开终端然后输入whichpython3 python3--versionpip3--version如果which python3返回/opt/homebrew/bin/python3并且版本号正确则说明配置成功。1.2.4 (可选但推荐) 安装 OllamaOllama 是一个专门为在本地运行 LLM 而设计的工具对 Apple Silicon 的 Metal 加速支持得非常好使用起来极其简单。访问 Ollama 官网。点击 “Download” 按钮下载.dmg文件。双击.dmg文件将Ollama应用拖拽到Applications文件夹中。首次启动 Ollama 时系统可能会提示“无法验证开发者”请前往系统设置 - 隐私与安全性点击“仍要打开”。Ollama 启动后会在菜单栏显示一个图标并在后台运行。您可以通过终端命令ollama list来验证它是否正常工作。第二章获取与配置 OpenClaw现在我们正式开始部署 OpenClaw。2.1 克隆 OpenClaw 仓库打开终端。选择一个合适的目录来存放项目例如~/projects。执行以下命令进入该目录mkdir-p~/projectscd~/projects克隆 OpenClaw 的官方仓库gitclone https://github.com/claw-org/openclaw.git进入项目目录cdopenclaw2.2 创建并激活 Python 虚拟环境使用虚拟环境可以隔离项目依赖避免与其他 Python 项目产生冲突。# 创建名为 venv 的虚拟环境python3-mvenv venv# 激活虚拟环境sourcevenv/bin/activate激活成功后您会看到命令行前缀变成了(venv)。2.3 安装 Python 依赖在激活的虚拟环境中安装项目所需的所有 Python 库。# 升级 pip 到最新版python-mpipinstall--upgradepip# 安装项目依赖pipinstall-rrequirements.txt常见坑点及解决方案Mac 特有faiss安装失败faiss是 Facebook 开源的向量相似度搜索库。在 Apple Silicon 上直接通过pip安装预编译的faiss-cpu通常没有问题。但如果遇到错误可以尝试先用 Homebrew 安装其依赖brewinstallswig然后再运行pip install faiss-cpu。tokenizers或torch安装缓慢这些库很大且默认从 PyPI 下载。可以使用国内镜像源加速pipinstall-rrequirements.txt-ihttps://pypi.tuna.tsinghua.edu.cn/simple2.4 配置.env文件OpenClaw 使用.env文件来管理各种配置项。项目根目录下通常有一个.env.example文件我们需要将其复制并重命名为.env然后根据自己的需求进行修改。复制文件cp.env.example .env用 VS Code、Sublime Text 或nano打开.env文件。关键配置项解释针对 Mac Ollama 优化VECTOR_STOREfaiss指定向量数据库。我们这里使用faiss。EMBEDDING_MODELBAAI/bge-small-zh-v1.5强烈推荐使用这个中文嵌入模型它在中文任务上表现优异。如果您主要处理英文可以使用sentence-transformers/all-MiniLM-L6-v2。LLM_MODEL_TYPEollama指定 LLM 的来源。我们这里使用ollama因为它能完美利用 Apple Silicon 的 GPU。OLLAMA_MODELqwen:7b指定 Ollama 中要使用的具体模型。qwen通义千问是一个优秀的开源中文模型。您也可以选择llama3:8b、phi3:mini等。注意首次使用模型时Ollama 会自动下载这可能需要一些时间。UPLOAD_DIR./uploads指定用户上传文件的存储目录。FAISS_PATH./vector_store指定 Faiss 向量数据库的持久化路径。配置示例VECTOR_STOREfaiss EMBEDDING_MODELBAAI/bge-small-zh-v1.5 LLM_MODEL_TYPEollama OLLAMA_MODELqwen:7b UPLOAD_DIR./uploads FAISS_PATH./vector_store第三章启动服务与基础测试完成配置后我们就可以启动 OpenClaw 服务了。3.1 预加载模型重要步骤为了确保服务启动时不会卡住建议先手动通过 Ollama 加载您在.env中指定的模型。# 在另一个终端窗口中不要在 (venv) 环境里ollama run qwen:7bOllama 会开始下载并加载qwen:7b模型。您会看到进度条。加载完成后您可以直接输入一个问题进行测试比如你好。测试完毕后按CtrlC退出。模型已经被缓存后续服务调用会非常快。3.2 启动后端 API 服务在激活的(venv)虚拟环境中运行以下命令uvicorn app.main:app--host0.0.0.0--port8000--reload--host 0.0.0.0允许局域网内的其他设备访问此服务。--port 8000服务监听的端口。--reload开启热重载方便开发调试。如果一切顺利您会看到类似Uvicorn running on http://0.0.0.0:8000的日志输出。3.3 (可选) 启动前端 Web UI如果项目包含前端界面进入frontend目录cdfrontend安装前端依赖需要先安装 Node.js。可通过brew install node安装npminstall启动前端开发服务器npmrun 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 安装 Ngrokbrewinstallngrok/ngrok/ngrok按照官网指引配置 AuthTokenngrok config add-authtokenyour_auth_token启动隧道ngrok http8000将 Ngrok 提供的公网地址如https://xxxx.ngrok-free.app填入飞书后台的 “请求网址”。4.3 修改 OpenClaw 以支持飞书 Webhook这部分代码逻辑与 Windows 教程完全一致。您需要在 FastAPI 后端增加一个处理飞书事件的路由并实现签名验证、消息解析和回复发送的逻辑。在.env文件中添加飞书配置FEISHU_VERIFY_TOKENyour_token_here FEISHU_ENCRYPT_KEYyour_key_here编写或集成飞书 Webhook 处理代码参考 Windows 教程中的代码片段。实现send_message_to_feishu函数用于调用飞书 API 发送消息。完成以上步骤后重启您的 OpenClaw 服务。现在在飞书群聊中 您的机器人并提问它就应该能利用您 Mac 本地的知识库给出回答了得益于 Apple Silicon 的强大性能响应速度会非常快。恭喜您您已经成功在 Mac 上部署了 OpenClaw 并将其接入飞书充分利用了您 Mac 的强大算力打造了一个私有、安全、高效的智能助手。如果您在操作过程中遇到任何问题或者觉得这篇教程对您有帮助欢迎在评论区留言交流。别忘了点赞、收藏、关注以便获取更多 AI 和 macOS 开发相关的实战教程