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

目录

• 一、前言
• 1.1 什么是 OpenClaw？
• 1.2 为什么要本地部署？
• 1.3 本文适合谁？
• 二、环境准备
• 2.1 系统要求
• 2.2 检查系统版本
• 2.3 安装 Homebrew（如果没有）
• 2.4 安装 Node.js
• 2.5 安装 Git
• 三、安装 OpenClaw
• 3.1 全局安装 OpenClaw
• 3.2 初始化工作区
• 3.3 启动 Gateway
• 四、配置 API 密钥
• 4.1 获取 API 密钥
• 4.2 配置认证文件
• 4.3 设置默认模型
• 五、首次运行
• 5.1 启动 Web 聊天界面
• 5.2 第一次对话
• 5.3 测试基本功能
• 六、核心文件说明
• 6.1 工作区结构
• 6.2 关键文件说明
• 七、常用命令速查
• 7.1 Gateway 管理
• 7.2 会话管理
• 7.3 技能管理
• 7.4 配置管理
• 八、实用配置示例
• 8.1 配置定时检查（HEARTBEAT.md）
• 8.2 配置 Cron 任务
• 九、常见问题
• Q1: 启动失败，提示端口占用
• Q2: API 密钥无效
• Q3: 文件无法读写
• Q4: 中文乱码
• Q5: 内存占用过高
• 十、进阶玩法
• 10.1 自定义技能
• 10.2 浏览器自动化
• 10.3 多设备联动
• 10.4 消息推送
• 十一、总结
• 11.1 部署流程回顾
• 11.2 下一步建议
• 11.3 注意事项
• 附录：完整命令清单

摘要： 本文详细介绍如何在 macOS 本地部署 OpenClaw 智能助理框架，从环境准备到首次运行，手把手教你搭建属于自己的 AI 助理。适合零基础新手，全程实操无坑 

关键词： OpenClaw、macOS、AI 助理、本地部署、Node.js

OpenClaw 是一个本地运行的 AI 助理框架，和普通的聊天机器人不一样：

• ✅ 有记忆 – 记住你们之间的对话和约定
• ✅ 有手脚 – 能读写文件、执行命令、控制浏览器
• ✅ 能主动 – 定时检查邮件、日历、项目状态
• ✅ 可扩展 – 支持技能系统，自定义功能

简单说：它不是陪你聊天的 AI，是能帮你干活的助理。

对比项	云端 AI	OpenClaw 本地部署
数据隐私	数据上传云端	所有数据本地存储
文件访问	无法访问本地文件	完整读写权限
命令执行	不支持	可执行 shell 命令
定制性	有限	完全可定制
成本	按次付费	一次部署，免费使用

• ✅ Mac 用户（Intel/Apple Silicon 均可）
• ✅ 零基础新手（会打开终端就行）
• ✅ 想拥有自己的 AI 助理
• ❌ 想用 Windows/Linux 的（本文不覆盖）

• 操作系统： macOS 12.0 或更高版本
• 处理器： Intel 或 Apple Silicon（M1/M2/M3）
• 内存： 至少 8GB（推荐 16GB）
• 磁盘空间： 至少 5GB 可用空间

打开终端（Terminal），输入：

sw_vers

输出示例：

ProductName:    macOS
ProductVersion: 14.2
BuildVersion:   23C64

Homebrew 是 macOS 的包管理器，OpenClaw 依赖它。

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

安装完成后，根据提示执行初始化命令（Apple Silicon 用户）：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

验证安装：

brew --version

OpenClaw 基于 Node.js 运行。

brew install node

验证安装：

node --version
npm --version

注意： 需要 Node.js v18 或更高版本

brew install git

验证：

git --version

npm install -g openclaw

安装完成后验证：

openclaw --version

openclaw init

这个命令会：

1. 创建配置目录 ~/.openclaw
2. 初始化工作区 ~/.openclaw/workspace
3. 生成默认配置文件

Gateway 是 OpenClaw 的核心服务：

openclaw gateway start

验证状态：

openclaw gateway status

看到 running 表示成功！

OpenClaw 支持多个 AI 模型提供商，选择一个：

提供商	模型	获取地址
阿里云百炼	Qwen3.5	https://bailian.console.aliyun.com
OpenAI	GPT-4	https://platform.openai.com
Google	Gemini	https://makersuite.google.com

编辑认证文件：

nano ~/.openclaw/agents/main/agent/auth-profiles.json

添加你的 API 密钥（以阿里云为例）：

{
  "bailian": {
    "apiKey": "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

提示： 按 Ctrl+O 保存，Ctrl+X 退出

编辑配置文件：

nano ~/.openclaw/gateway/config.json

添加或修改：

{
  "default_model": "bailian/qwen3.5-plus"
}

openclaw webchat

浏览器会自动打开，访问 http://localhost:3000

启动后，OpenClaw 会读取 BOOTSTRAP.md 引导你：

1. 给自己起个名字（比如：小助手、Jarvis）
2. 设定性格（正式/ casual/ 毒舌）
3. 填写 USER.md（告诉它你的信息）

在聊天框输入：

帮我创建一个测试文件

它应该会在工作区创建一个文件并告诉你位置。

~/.openclaw/workspace/
├── MEMORY.md          # 长期记忆（重要！）
├── USER.md            # 用户信息
├── SOUL.md            # AI 人格设定
├── IDENTITY.md        # AI 身份信息
├── HEARTBEAT.md       # 定时任务配置
├── TOOLS.md           # 工具配置笔记
└── memory/            # 每日日志目录
    └── YYYY-MM-DD.md

文件	作用	是否需要修改
MEMORY.md	存储长期记忆	让它自动维护
USER.md	你的个人信息	需要填写
SOUL.md	AI 人格设定	可选修改
HEARTBEAT.md	定时任务	根据需要添加

openclaw gateway start      # 启动服务
openclaw gateway stop       # 停止服务
openclaw gateway restart    # 重启服务
openclaw gateway status     # 查看状态

openclaw sessions list      # 查看会话列表
openclaw sessions spawn     # 创建子会话

openclaw skills list        # 查看已安装技能
openclaw skills install     # 安装新技能

openclaw config get         # 查看配置
openclaw config patch       # 修改配置

编辑 ~/.openclaw/workspace/HEARTBEAT.md：

# 每 2 小时检查一次
## 邮箱检查
如果有未读邮件，提醒我。
## 日历检查
如果有 2 小时内的会议，提前通知。
## 天气检查
如果要下雨，提醒带伞。

openclaw cron add

示例：每天早上 9 点提醒

{
  "name": "morning-reminder",
  "schedule": {
    "kind": "cron",
    "expr": "0 9 * * *",
    "tz": "Asia/Shanghai"
  },
  "payload": {
    "kind": "systemEvent",
    "text": "早上好！今天有什么安排？"
  },
  "sessionTarget": "main",
  "enabled": true
}

解决：

lsof -i :3000
kill -9 <PID>
openclaw gateway restart

检查：

1. 确认密钥格式正确
2. 确认账户有余额
3. 重启 Gateway：openclaw gateway restart

检查权限：

ls -la ~/.openclaw/workspace/
chmod -R 755 ~/.openclaw/workspace/

解决： 确保终端编码为 UTF-8

export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8

解决： 定期清理会话

openclaw sessions list
# 清理不需要的会话

在 ~/.openclaw/skills/ 目录下创建新技能：

my-skill/
├── SKILL.md      # 技能说明
├── script.sh     # 执行脚本
└── assets/       # 资源文件

OpenClaw 可以控制浏览器：

帮我打开 GitHub，查看我的仓库列表

如果有多个设备，可以配置 node 联动：

openclaw nodes status

配置后可通过 Telegram/WhatsApp/Discord 接收消息：

openclaw message send --target <channel> --message "测试消息"

1. ✅ 安装 Homebrew、Node.js、Git
2. ✅ npm install -g openclaw
3. ✅ openclaw init 初始化
4. ✅ openclaw gateway start 启动
5. ✅ 配置 API 密钥
6. ✅ openclaw webchat 开始使用

• 📚 阅读官方文档：/opt/homebrew/lib/node_modules/openclaw/docs
• 🔗 加入社区：https://discord.com/invite/clawd
• 🛠️ 探索技能市场：https://clawhub.com
• 📝 完善 USER.md 和 MEMORY.md

• ⚠️ 定期备份 ~/.openclaw/workspace 目录
• ⚠️ 不要随意删除 MEMORY.md
• ⚠️ API 密钥妥善保管，不要上传到公开仓库
• ⚠️ 执行外部命令前确认安全性

# 环境检查
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+

以上就是Mac本地部署OpenClaw的完整教程(新手小白必看)的详细内容，更多关于Mac本地部署OpenClaw的资料请关注风君子博客其它相关文章！