Mac 本地部署 OpenClaw 智能助理框架教程

一、简介

1.1 什么是 OpenClaw？

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

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

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

1.2 为什么要本地部署？

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

二、环境准备

2.1 系统要求

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

2.2 检查系统版本

打开终端（Terminal），输入：

sw_vers

输出示例：

ProductName: macOS ProductVersion: 14.2 BuildVersion: 23C64

2.3 安装 Homebrew（如果没有）

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

2.4 安装 Node.js

OpenClaw 基于 Node.js 运行。

brew install node

验证安装：

node --version
npm --version

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

2.5 安装 Git

brew install git

验证：

git --version

三、安装 OpenClaw

3.1 全局安装 OpenClaw

npm install -g openclaw

安装完成后验证：

openclaw --version

3.2 初始化工作区

openclaw init

这个命令会：

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

3.3 启动 Gateway

Gateway 是 OpenClaw 的核心服务：

openclaw gateway start

验证状态：

openclaw gateway status

看到 running 表示成功！

四、配置 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 配置认证文件

编辑认证文件：

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

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

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

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

4.3 设置默认模型

编辑配置文件：

nano ~/.openclaw/gateway/config.json

添加或修改：

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

五、首次运行

5.1 启动 Web 聊天界面

openclaw webchat

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

5.2 第一次对话

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

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

5.3 测试基本功能

在聊天框输入：

帮我创建一个测试文件

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

六、核心文件说明

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 管理

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

7.2 会话管理

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

7.3 技能管理

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

7.4 配置管理

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

八、实用配置示例

8.1 配置定时检查（HEARTBEAT.md）

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

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

8.2 配置 Cron 任务

openclaw cron add

示例：每天早上 9 点提醒

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

九、常见问题

Q1: 启动失败，提示端口占用

解决：

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

Q2: API 密钥无效

检查：

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

Q3: 文件无法读写

检查权限：

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

Q4: 中文乱码

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

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

Q5: 内存占用过高

解决： 定期清理会话

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

十、进阶玩法

10.1 自定义技能

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

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

10.2 浏览器自动化

OpenClaw 可以控制浏览器：

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

10.3 多设备联动

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

openclaw nodes status

10.4 消息推送

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

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

十一、总结

11.1 部署流程回顾

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

11.2 注意事项

⚠️ 定期备份 ~/.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

Mac 本地部署 OpenClaw 智能助理框架教程