基于本地 Mac 从 0 到 1 部署 OpenClaw

2026年开年最火的个人 AI 智能体工具，GitHub 星标 21.5万+，日增星标 3800+，一款能通过聊天软件发指令、自动帮你整理文件、处理邮件、运行脚本、同步日程的 AI 助手。

目录

• 一、OpenClaw 是什么？
• 二、系统要求
• 三、环境准备
• 四、部署方式
• 五、配置大模型 API
• 六、连接聊天软件（可选）
• 七、故障排查
• 八、总结

---

一、OpenClaw 是什么？

OpenClaw 是一款开源的个人 AI 智能体工具，它能够：

• 🤖 通过聊天软件（微信、钉钉、飞书等）发指令
• 📁 自动帮你整理文件
• 📧 处理邮件
• 🔧 运行脚本
• 📅 同步日程

不同于传统只能提供建议的 AI 工具，OpenClaw 可以真正执行任务，成为你的数字化个人助理。

---

二、系统要求

配置项	最低要求	推荐配置
操作系统	macOS 12+	macOS 14+
内存	2GB	4GB+
存储空间	5GB	10GB+
网络	能访问 GitHub 和 npm	稳定的国际网络连接

---

三、环境准备

3.1 安装 Homebrew（如果还没有）

打开终端，执行：

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

3.2 安装 Node.js（必须 ≥22 版本）

⚠️ 易错点：Node.js 版本过低是 90% 安装失败的根源！

推荐方式：使用 nvm 管理 Node 版本

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 使配置生效
source ~/.zshrc

# 安装 Node.js 22
nvm install 22
nvm use 22

# 设置为默认版本
nvm alias default 22

验证安装：

node -v
# 应显示 v22.x.x 或更高版本

npm -v
# 应显示 10.x.x 或更高版本

3.3 安装 pnpm（推荐）

npm install -g pnpm

3.4 安装 Git

brew install git

---

四、部署方式

OpenClaw 提供三种部署方式，根据你的需求选择：

方式一：一键脚本安装（推荐新手 ⭐⭐⭐⭐⭐）

最简单、最推荐的安装方式：

# 执行安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

验证安装：

openclaw --version
# 如果显示版本号（如 openclaw v2.1.0），说明安装成功

初始化配置：

# 启动配置向导
openclaw init

按照提示完成：

1. 选择模型提供方（OpenAI、Gemini、Claude、国内大模型等）
2. 输入 API Key
3. 选择连接渠道（微信、钉钉、飞书等，可选）
4. 设置数据存储路径（建议使用默认）

启动服务：

# 启动服务
openclaw start

# 或者以后台模式运行
openclaw start --daemon

---

方式二：Docker 部署（推荐进阶用户 ⭐⭐⭐⭐）

Docker 部署的优势是环境隔离、便于迁移。

4.2.1 安装 Docker Desktop

brew install --cask docker

安装完成后，启动 Docker Desktop 应用。

4.2.2 创建项目目录

mkdir -p ~/openclaw
cd ~/openclaw

4.2.3 创建 docker-compose.yml 文件

version: '3.8'

services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    environment:
      - NODE_ENV=production
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - MODEL_PROVIDER=openai
      - MODEL_NAME=gpt-4
    restart: unless-stopped

4.2.4 创建环境变量文件

# 创建 .env 文件
echo "OPENAI_API_KEY=your-api-key-here" > .env

4.2.5 启动容器

# 拉取镜像并启动
docker-compose up -d

# 查看日志
docker-compose logs -f

# 查看运行状态
docker ps

---

方式三：手动安装（适合开发者 ⭐⭐⭐）

适合需要深度定制或二次开发的用户。

4.3.1 克隆仓库

# 克隆官方仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

如果克隆失败，可以使用镜像加速：

git clone https://ghproxy.com/https://github.com/openclaw/openclaw.git

4.3.2 安装依赖

# 安装项目依赖
pnpm install

# 构建前端
pnpm ui:build

# 构建项目
pnpm build

⚠️ 如果安装速度慢，可以使用国内镜像：

npm config set registry https://registry.npmmirror.com

4.3.3 配置环境变量

# 复制配置模板
cp .env.example .env

# 编辑配置文件
vim .env

最小配置示例：

# 模型配置
MODEL_PROVIDER=openai
OPENAI_API_KEY=sk-your-api-key-here
MODEL_NAME=gpt-4

# 服务配置
PORT=3000
HOST=0.0.0.0

# 数据存储
DATA_DIR=./data

4.3.4 初始化并启动

# 执行初始化配置
openclaw onboard --install-daemon

# 启动服务
node openclaw.mjs gateway --port 3000 --verbose

---

五、配置大模型 API

无论哪种部署方式，都需要配置大模型 API 才能正常使用。

5.1 获取 API Key

OpenAI：

1. 访问 https://platform.openai.com
2. 注册/登录账号
3. 进入 API Keys 页面，创建新 Key

国内大模型（以通义千问为例）：

1. 访问 https://dashscope.aliyun.com
2. 注册阿里云账号
3. 创建 API Key

5.2 配置模型

通过命令行配置：

# 设置模型提供方
openclaw config set model.provider openai

# 设置 API Key
openclaw config set model.openai.apiKey sk-your-key-here

# 设置模型名称
openclaw config set model.name gpt-4

# 验证配置
openclaw config get model

通过 Web 界面配置：

1. 访问 http://localhost:3000
2. 点击"设置" → “模型配置”
3. 填写 API 信息并保存

⚠️ 注意：API Key 不要泄露，建议保存在环境变量中：

export OPENAI_API_KEY="your-api-key-here"

---

六、连接聊天软件（可选）

OpenClaw 支持接入多种聊天软件，实现通过聊天界面控制 AI。

6.1 连接微信

# 安装微信适配器
openclaw plugin install wechat

# 配置微信
openclaw config set channels.wechat.enabled true

# 重启服务
openclaw restart

6.2 连接钉钉

# 安装钉钉适配器
openclaw plugin install dingtalk

# 在钉钉开放平台创建机器人，获取 Webhook 地址和 Secret
openclaw config set channels.dingtalk.enabled true
openclaw config set channels.dingtalk.webhookUrl https://oapi.dingtalk.com/robot/send?access_token=xxx
openclaw config set channels.dingtalk.secret your-secret

6.3 连接飞书

# 安装飞书适配器
openclaw plugin install feishu

# 配置飞书
openclaw config set channels.feishu.enabled true

---

七、故障排查

7.1 检查服务状态

# 查看 OpenClaw 状态
openclaw status

# 查看网关状态
openclaw gateway probe

# 查看实时日志
openclaw logs --follow

7.2 常见问题

问题 1：端口被占用

# 错误信息：Port 3000 is already in use

# 解决：更换端口
openclaw start --port 3001

# 或者查找并关闭占用端口的进程
lsof -i :3000
kill -9 <进程ID>

问题 2：权限不足

# 错误信息：EACCES: permission denied

# 解决：修改目录权限
sudo chown -R $(whoami) ~/.openclaw

问题 3：模型连接失败

# 检查网络连接
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer your-api-key"

# 如果超时，检查网络或代理设置

问题 4：Docker 容器无法启动

# 查看详细错误
docker-compose logs

# 常见问题：镜像拉取失败
# 解决：配置 Docker 镜像加速

编辑 Docker 配置文件：

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

---

八、总结

部署方式对比

部署方式	难度	适用场景	推荐度
一键脚本	⭐	个人使用、快速体验	⭐⭐⭐⭐⭐
Docker	⭐⭐	服务器部署、团队协作	⭐⭐⭐⭐
手动安装	⭐⭐⭐	二次开发、深度定制	⭐⭐⭐

关键成功要素

1. ✅ Node.js 版本必须 ≥22
2. ✅ 路径不要有中文
3. ✅ API Key 要保密且有余额
4. ✅ 遇到问题先看日志

常用命令速查

# 启动服务
openclaw start

# 停止服务
openclaw stop

# 重启服务
openclaw restart

# 查看状态
openclaw status

# 查看日志
openclaw logs --follow

# 升级
curl -fsSL https://openclaw.ai/install.sh | bash

# 卸载
openclaw uninstall

---

参考资源

• OpenClaw 官方网站
• OpenClaw GitHub 仓库
• OpenAI API 文档
• 阿里云通义千问

---

🎉 恭喜！ 现在你已经拥有了自己的 AI 智能体。开始探索 OpenClaw 的强大功能吧！