Mac本地部署OpenClaw完整教程｜新手小白必看

摘要： 本文详细介绍如何在 macOS 本地部署 OpenClaw 智能助理框架，从环境准备到首次运行，手把手教你搭建属于自己的 AI 助理。适合零基础新手，全程实操无坑 关键词： OpenClaw、macOS、AI 助理、本地部署、Node.js 一、前言 在正式动手之前，先来聊两句大背景。AI 助理这个赛道现在卷得厉害，但绝大多数都是云端产品，数据传上去、结果拿回来。对于一些对隐私、权限或者自定义能力有要求的用户来说，这显然不够用。OpenClaw 就属于一条完全不同的路——它是个本地运行的框架，数据、文件、甚至命令行，全在你自己掌控之下。 1.1 什么是 OpenClaw？ 它不是一个普通的聊天机器人。普通聊天机器人，要么记不住之前说过的话，要么只能发几句套话。但 OpenClaw 更像一个“有手有脚”的数字助理： * ✅ **有记忆** - 它记得你们之间的所有对话和约定，不会每次都得从头介绍自己。 * ✅ **有手脚** - 能读写文件、执行系统命令、控制浏览器，这不是陪你闲聊的玩具。 * ✅ **能主动** - 可以定时检查邮件、日历、项目状态，到了点主动提醒你。 * ✅ **可扩展** - 支持自定义技能系统，你想让它干什么，自己装个技能就行。 一句话总结：**它不是陪你聊天的 AI，是能帮你干活的助理。** 1.2 为什么要本地部署？ 云端 AI 当然很方便，但碰到数据隐私、文件访问这些硬需求的时候，就露怯了。下面这张表把核心差异摆得更清楚： | 对比项 | 云端 AI | OpenClaw 本地部署 | | --- | --- | --- | | 数据隐私 | 数据上传云端 | 所有数据本地存储 | | 文件访问 | 无法访问本地文件 | 完整读写权限 | | 命令执行 | 不支持 | 可执行 shell 命令 | | 定制性 | 有限 | 完全可定制 | | 成本 | 按次付费，钱&包吃不消 | 一次部署，免费使用 | 1.3 本文适合谁？ 这篇教程主要面向以下群体： * ✅ Mac 用户（Intel 芯或 Apple Silicon 芯片都可以） * ✅ 零基础新手（能打开终端、会复制粘贴命令就行） * ✅ 想拥有自己的 AI 助理，但不想被云服务绑死 * ❌ 想用 Windows 或 Linux 的（本文不覆盖，不过思路是相通的） 二、环境准备 动手之前，得先把工具箱备齐。这部分虽然有点琐碎，但每一步都关系到后面能不能顺利跑起来。 2.1 系统要求 硬件上没什么特别变态的门槛，但基本的及格线还是有的： * **操作系统：** macOS 12.0 或更高版本 * **处理器：** Intel 或 Apple Silicon（M1/M2/M3） * **内存：** 至少 8GB，推荐 16GB（运行时资源消耗不算低） * **磁盘空间：** 至少 5GB 可用空间（主要存储模型配置、会话日志和工作区文件） 2.2 检查系统版本 首先，打开 **终端**（Terminal），运行下面这条命令： ```bash sw_vers ``` 输出应该类似这样： ```bash ProductName: macOS ProductVersion: 14.2 BuildVersion: 23C64 ``` 如果版本号是 12.0 或以上，就可以放心往下走。 2.3 安装 Homebrew（如果没有） Homebrew 是 macOS 上最主流的包管理器，OpenClaw 的很多依赖都需要通过它来安装。官方安装脚本很好记： ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" ``` 安装完成后，根据终端里的提示执行初始化命令。如果是 Apple Silicon 用户，通常需要运行： ```bash echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)" ``` 最后验证一下安装是否成功： ```bash brew --version ``` 如果返回了版本号，Homebrew 就准备好服役了。 2.4 安装 Node.js OpenClaw 跑在 Node.js 上，所以这一步不能省。直接用 Homebrew 安装： ```bash brew install node ``` 安装完成后，验证版本： ```bash node --version npm --version ``` 这里有个硬性要求：**Node.js 版本必须不低于 v18**。如果版本太老，后面可能会碰到兼容性问题。 2.5 安装 Git Git 是版本控制工具，OpenClaw 在安装技能或更新时会用到： ```bash brew install git ``` 验证： ```bash git --version ``` 三、安装 OpenClaw 环境都准备好了，接下来进入到主角登场环节。 3.1 全局安装 OpenClaw 用 npm 全局安装，命令非常简单： ```bash npm install -g openclaw ``` 安装完成后，同样要验证一下： ```bash openclaw --version ``` 如果输出版本号，说明安装成功。 3.2 初始化工作区 安装只是第一步，还需要初始化工作区，这个过程会创建配置文件和默认目录： ```bash openclaw init ``` 这个命令主要干了三件事： 1. 创建配置目录 `~/.openclaw` 2. 初始化工作区 `~/.openclaw/workspace` 3. 生成默认配置文件 3.3 启动 Gateway Gateway 是 OpenClaw 的核心服务，相当于整个框架的发动机： ```bash openclaw gateway start ``` 启动后，可以用状态命令确认它是否在运行： ```bash openclaw gateway status ``` 如果输出 `running`，说明核心服务已经成功启动，万事俱备只欠东风了。 四、配置 API 密钥 OpenClaw 本身只是一个框架，底层的 AI 推理能力还需要依赖第三方大模型提供商的 API。这里需要配置一个 API 密钥。 4.1 获取 API 密钥 OpenClaw 支持多个 AI 模型提供商，选一个自己习惯的就行： | 提供商 | 模型 | 获取地址 | | --- | --- | --- | | 阿里云百炼 | Qwen3.5 | https://bailian.console.aliyun.com | | OpenAI | GPT-4 | https://platform.openai.com | | Google | Gemini | https://makersuite.google.com | 4.2 配置认证文件 获取到 API 密钥后，需要将其写入认证配置文件。编辑文件： ```bash nano ~/.openclaw/agents/main/agent/auth-profiles.json ``` 以阿里云百炼为例，填入以下内容： ```json { "bailian": { "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxx" } } ``` > **提示：** 在 nano 编辑器中，按 Ctrl+O 保存，Ctrl+X 退出。 4.3 设置默认模型 最后一步是告诉 OpenClaw 默认使用哪个模型。编辑配置文件： ```bash nano ~/.openclaw/gateway/config.json ``` 添加或修改 `default_model` 字段，比如： ```json { "default_model": "bailian/qwen3.5-plus" } ``` 五、首次运行 配置全部就绪，按下启动按钮。 5.1 启动 Web 聊天界面 在终端里运行： ```bash openclaw webchat ``` 命令执行后，浏览器会自动打开，访问 `http://localhost:3000`。看到聊天界面，就说明部署成功了。 5.2 第一次对话 首次启动时，OpenClaw 会读取 `BOOTSTRAP.md` 文件，引导你完成三个基础设定： 1. **给自己起个名字**（比如：小助手、Jarvis，全凭你喜好） 2. **设定性格风格**（正式、casual、毒舌——选哪个都能体验不同的交互感） 3. **填写 USER.md**（告诉它你的个人信息，比如姓名、职业、常用工具等） 5.3 测试基本功能 设定完成后，在聊天框里试试最基本的文件操作： ``` 帮我创建一个测试文件 ``` 正常情况下，它应该会提示在工作区创建了一个文件，并告诉你文件的具体路径。 六、核心文件说明 OpenClaw 的工作区目录结构比较清晰，了解这些文件的作用，能帮你更好地管理自己的 AI 助理。 6.1 工作区结构 ``` ~/.openclaw/workspace/ ├── MEMORY.md # 长期记忆（非常重要！） ├── USER.md # 用户信息 ├── SOUL.md # AI 人格设定 ├── IDENTITY.md # AI 身份信息 ├── HEARTBEAT.md # 定时任务配置 ├── TOOLS.md # 工具配置笔记 └── memory/ # 每日日志目录 └── YYYY-MM-DD.md ``` 6.2 关键文件说明 | 文件 | 作用 | 是否需要修改 | | --- | --- | --- | | MEMORY.md | 存储长期记忆，相当于数字大脑 | 让它自动维护就好 | | USER.md | 你的个人信息 | **需要手动填写** | | SOUL.md | AI 人格设定 | 可选修改，按需调整 | | HEARTBEAT.md | 定时任务配置 | 根据需要添加 | 七、常用命令速查 日常维护时，下面这些命令会频繁用到，建议收藏或者记个笔记。 7.1 Gateway 管理 ```bash openclaw gateway start # 启动服务 openclaw gateway stop # 停止服务 openclaw gateway restart # 重启服务 openclaw gateway status # 查看状态 ``` 7.2 会话管理 ```bash openclaw sessions list # 查看会话列表 openclaw sessions spawn # 创建子会话 ``` 7.3 技能管理 ```bash openclaw skills list # 查看已安装技能 openclaw skills install # 安装新技能 ``` 7.4 配置管理 ```bash openclaw config get # 查看当前配置 openclaw config patch # 修改配置 ``` 八、实用配置示例 理论说完了，来点实际的。下面两个配置案例，可以让你的 AI 助理变得更“主动”。 8.1 配置定时检查（HEARTBEAT.md） 编辑 `~/.openclaw/workspace/HEARTBEAT.md`，写入你想让它定时做的事情： ``` # 每 2 小时检查一次 ## 邮箱检查 如果有未读邮件，提醒我。 ## 日历检查 如果有 2 小时内的会议，提前通知。 ## 天气检查 如果要下雨，提醒带伞。 ``` 8.2 配置 Cron 任务 如果想在特定时间触发提醒，可以配置 cron 任务： ```bash openclaw cron add ``` 比如配置一个每天早上 9 点的早安提醒： ```json { "name": "morning-reminder", "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" }, "payload": { "kind": "systemEvent", "text": "早上好！今天有什么安排？" }, "sessionTarget": "main", "enabled": true } ``` 九、常见问题 部署过程中难免遇到一些小坑。下面汇总一下最常见的几个问题及解决思路。 **Q1: 启动失败，提示端口占用** **解决方案：** 先找到占用 3000 端口的进程，然后杀掉它再重启服务 ```bash lsof -i :3000 kill -9 openclaw gateway restart ``` **Q2: API 密钥无效** **检查步骤：** 1. 确认密钥格式正确，不要有多余的引号或空格 2. 确认账户内有余额（大部分服务都需要预充值） 3. 重启 Gateway：`openclaw gateway restart`，让新配置生效 **Q3: 文件无法读写** **检查权限：** ```bash ls -la ~/.openclaw/workspace/ chmod -R 755 ~/.openclaw/workspace/ ``` **Q4: 中文乱码** **解决方案：** 手动设置终端编码为 UTF-8 ```bash export LANG=zh_CN.UTF-8 export LC_ALL=zh_CN.UTF-8 ``` **Q5: 内存占用过高** **解决方案：** 定期清理会话，删除不再需要的对话历史 ```bash openclaw sessions list # 然后手动清理不需要的会话 ``` 十、进阶玩法 如果基础功能已经玩腻了，下面这几个方向可以让你把 OpenClaw 的潜力再挖一挖。 10.1 自定义技能 在 `~/.openclaw/skills/` 目录下创建新技能文件夹，结构类似这样： ``` my-skill/ ├── SKILL.md # 技能说明 ├── script.sh # 执行脚本 └── assets/ # 资源文件 ``` 10.2 浏览器自动化 OpenClaw 可以控制浏览器，执行一些自动化操作。在聊天框里直接说： ``` 帮我打开 GitHub，查看我的仓库列表 ``` 10.3 多设备联动 如果有多个设备，可以配置 node 联动，让它们协同工作： ```bash openclaw nodes status ``` 10.4 消息推送 配置好推送渠道后，OpenClaw 可以通过 Telegram、WhatsApp、Discord 等平台给你发送消息： ```bash openclaw message send --target --message "测试消息" ``` 十一、总结 11.1 部署流程回顾 从零到一，整个流程走下来其实并不复杂： 1. ✅ 安装 Homebrew、Node.js、Git 2. ✅ `npm install -g openclaw` 3. ✅ `openclaw init` 初始化工作区 4. ✅ `openclaw gateway start` 启动服务 5. ✅ 配置 API 密钥 6. ✅ `openclaw webchat` 开始使用 11.2 下一步建议 部署完成只是起点，真正有意思的是后面的个性化配置： * ???? 阅读官方文档：`/opt/homebrew/lib/node_modules/openclaw/docs` * ???? 加入社区，看看别人都在怎么用 * ????️ 探索技能市场，发现更多实用技能 * ???? 完善 USER.md 和 MEMORY.md，让助理更懂你 11.3 注意事项 最后，几个提醒必须放在心上： * ⚠️ **定期备份** `~/.openclaw/workspace` 目录，别等数据丢了才后悔 * ⚠️ **不要随意删除** MEMORY.md，那是助理的长期记忆 * ⚠️ **妥善保管 API 密钥**，不要上传到公开仓库或论坛 * ⚠️ **谨慎授权外部命令执行**，确认脚本安全性后再放行 附录：完整命令清单 ```bash # 环境检查 sw_vers node --version npm --version git --version # 安装 npm install -g openclaw # 初始化 openclaw init openclaw gateway start openclaw gateway status # 使用 openclaw webchat openclaw sessions list openclaw cron list # 维护 openclaw gateway restart openclaw config get ``` > **适用版本：** OpenClaw 最新版 > **系统：** macOS 12.0+

来源：互联网