1. OpenClaw 本地部署概述
OpenClaw 是一款基于大模型技术的智能助手工具,能够在本地环境中运行并提供多种实用功能。对于 Mac 用户来说,本地部署 OpenClaw 可以带来更快的响应速度和更好的隐私保护。本文将详细介绍在 Mac 电脑上部署 OpenClaw 的全过程,从环境准备到最终运行,涵盖所有关键步骤和常见问题的解决方案。
在开始部署前,我们需要了解几个关键点:首先,OpenClaw 需要 Node.js 运行环境;其次,它依赖于 Git 进行代码管理;最后,需要配置大模型 API 才能正常使用其核心功能。整个部署过程大约需要 10-15 分钟,具体时间取决于网络状况和电脑性能。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与检查
2.1 系统要求确认
在开始安装前,请确保您的 Mac 满足以下最低要求:
- 操作系统:macOS 12.0 (Monterey) 或更高版本
- 处理器:Intel 或 Apple Silicon (M1/M2/M3) 芯片
- 存储空间:至少 2GB 可用空间
- 内存:建议 8GB 或以上
要检查您的系统版本,可以点击屏幕左上角的苹果图标,选择"关于本机"。如果系统版本低于要求,建议先通过系统更新升级 macOS。
2.2 必要工具准备
安装 OpenClaw 需要以下几个必备工具:
- Homebrew:Mac 上的包管理器
- Node.js:JavaScript 运行时环境
- Git:版本控制系统
- npm:Node.js 的包管理器
这些工具将帮助我们顺利安装和运行 OpenClaw。如果您的系统中已经安装了部分工具,可以跳过相应步骤,但建议检查版本是否兼容。
2.3 权限与网络检查
在开始安装前,请完成以下检查:
- 打开"系统设置"→"隐私与安全性"→"完全磁盘访问",确保终端有完全磁盘访问权限
- 检查网络连接,确保可以访问 GitHub 等代码托管平台
- 如果您使用代理,请确保终端也能通过代理访问网络
这些检查可以避免后续安装过程中出现权限或网络相关的问题。
3. 基础环境安装
3.1 安装 Homebrew
Homebrew 是 Mac 上最受欢迎的包管理器,我们将使用它来安装其他依赖项。安装步骤如下:
- 打开终端(可通过 Spotlight 搜索"终端"或从"应用程序"→"实用工具"中找到)
- 复制并执行以下安装命令:
bash复制/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"
- 安装过程中会提示选择镜像源,建议选择国内镜像(如清华源或阿里源)以获得更快的下载速度
- 安装完成后,执行以下命令验证是否安装成功:
bash复制brew -v
如果显示 Homebrew 的版本号,说明安装成功。
对于 Apple Silicon (M系列)芯片的 Mac,还需要执行以下命令配置环境变量:
bash复制echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
3.2 安装 Node.js 和 npm
OpenClaw 需要 Node.js 运行环境,我们推荐安装 LTS(长期支持)版本以确保稳定性:
- 通过 Homebrew 安装 Node.js:
bash复制brew install node@20
- 配置环境变量:
bash复制echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
- 验证安装:
bash复制node -v
npm -v
两个命令都应显示版本号,确认安装成功。
3.3 安装和配置 Git
Git 是获取 OpenClaw 源代码的必要工具,安装步骤如下:
- 通过 Homebrew 安装 Git:
bash复制brew install git
- 验证安装:
bash复制git --version
- 为避免后续权限问题,建议执行以下配置:
bash复制git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"
git config --global url."https://github.com/".insteadOf "git@github.com:"
- (可选)配置 Git 用户信息:
bash复制git config --global user.name "您的名字"
git config --global user.email "您的邮箱"
4. OpenClaw 核心安装
4.1 安装 OpenClaw
完成基础环境准备后,可以开始安装 OpenClaw:
- 首先配置 npm 使用国内镜像加速下载:
bash复制npm config set registry http://registry.npmmirror.com
- 全局安装 OpenClaw:
bash复制npm install -g openclaw@latest
- 安装完成后验证:
bash复制openclaw -v
如果显示版本号,说明安装成功。
重要提示:安装过程中不要使用 sudo,否则可能导致权限问题。
4.2 初始化配置
安装完成后需要进行初始化配置:
- 执行初始化命令:
bash复制openclaw init
- 按照提示完成配置:
- 配置文件路径:直接回车使用默认路径
- 日志级别:回车使用默认 info 级别
- 服务端口:默认 9000(如被占用可改为其他端口)
- 设置后台管理用户名和密码(建议使用简单易记的组合)
初始化完成后会显示成功信息。
4.3 配置大模型 API
OpenClaw 需要大模型 API 才能正常工作,以下是两种配置方案:
方案一:阿里云通义千问(国内推荐)
- 打开配置文件:
bash复制open ~/.openclaw/config.yaml
- 修改 llm 配置段为:
yaml复制llm:
provider: dashscope
api_key: "您的通义千问API密钥"
model: "qwen-max"
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
方案二:OpenAI GPT
yaml复制llm:
provider: openai
api_key: "您的OpenAI API密钥"
model: "gpt-4o"
base_url: "https://api.openai.com/v1"
API 密钥获取方式:
- 通义千问:访问阿里云百炼平台 (https://dashscope.aliyun.com/) 创建 API 密钥
- OpenAI:登录 OpenAI 平台 (https://platform.openai.com/api-keys) 创建密钥
配置完成后保存文件,注意不要留下多余空格。
5. 启动与验证
5.1 启动 OpenClaw 服务
完成所有配置后,可以启动 OpenClaw:
- 执行启动命令:
bash复制openclaw start
- 成功启动后会显示服务运行地址(通常是 http://localhost:9000)
- 保持终端窗口打开,关闭窗口会停止服务
5.2 验证安装
可以通过多种方式验证安装是否成功:
- 终端命令验证:
bash复制openclaw status
应显示服务正在运行。
-
网页后台验证:
- 打开浏览器访问 http://localhost:9000
- 使用初始化时设置的用户名密码登录
- 成功进入后台管理界面说明安装成功
-
功能测试:
- 在后台对话界面输入测试指令
- 如:"帮我写一份 Mac 终端常用命令清单"
- 正常收到回复说明 API 配置正确
6. 常见问题解决
6.1 npm 安装错误
问题:npm error code 128
- 原因:Git 通过 SSH 拉取仓库失败
- 解决方案:
- 确保执行了 Git 的 HTTPS 配置
- 清理 npm 缓存:
bash复制npm cache clean --force
- 重新安装
问题:npm 权限不足 (EACCES)
- 原因:之前使用 sudo 安装导致权限问题
- 解决方案:
bash复制sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules
npm cache clean --force
然后重新安装(不要用 sudo)
6.2 命令找不到
问题:command not found
- 原因:环境变量未正确配置
- 解决方案:
- 重新执行对应软件的环境变量配置
- 刷新环境变量:
bash复制source ~/.zshrc
- 重启终端
- 如仍无效,重新安装对应软件
6.3 端口占用
问题:无法访问后台
- 原因:端口被占用或防火墙拦截
- 解决方案:
- 停止服务:
bash复制openclaw stop
- 修改配置文件中的端口号
- 重新启动服务
- 检查防火墙设置,允许终端网络访问
6.4 API 相关问题
问题:API 调用失败
- 原因:配置错误或密钥无效
- 解决方案:
- 检查配置文件中的 provider、model、base_url 和 api_key 是否匹配
- 确认 API 密钥有效且有足够额度
- 国内用户使用 OpenAI 需确保网络能访问其接口
- 重启 OpenClaw 使新配置生效
7. 进阶配置
7.1 接入办公软件
OpenClaw 可以集成到飞书、钉钉等办公平台:
- 打开 OpenClaw 后台的"集成"模块
- 选择要集成的平台(如飞书或钉钉)
- 按照指引创建企业应用并获取必要参数
- 将参数填入 OpenClaw 配置界面
- 保存并重启服务
配置完成后,可以直接在办公软件中使用 OpenClaw 功能。
7.2 使用本地大模型
通过 Ollama 可以使用本地大模型,无需 API 费用:
- 下载安装 Ollama (https://ollama.com/)
- 拉取模型(如通义千问):
bash复制ollama pull qwen
- 修改 OpenClaw 配置:
yaml复制llm:
provider: ollama
model: "qwen"
base_url: "http://localhost:11434/v1"
- 重启 OpenClaw 服务
7.3 开机自启
设置 OpenClaw 开机自动启动:
- 安装服务:
bash复制openclaw service install
- 如需取消:
bash复制openclaw service uninstall
8. 维护与更新
8.1 常用命令
| 命令 | 功能 |
|---|---|
openclaw start |
启动服务 |
openclaw stop |
停止服务 |
openclaw restart |
重启服务 |
openclaw status |
查看状态 |
openclaw logs |
查看日志 |
openclaw -v |
查看版本 |
8.2 更新 OpenClaw
定期更新可以获取最新功能和修复:
- 停止当前服务:
bash复制openclaw stop
- 更新到最新版本:
bash复制npm install -g openclaw@latest
- 重新启动服务
8.3 备份配置
建议定期备份配置文件:
bash复制cp ~/.openclaw/config.yaml ~/openclaw-config-backup.yaml
如需恢复,只需将备份文件复制回原位置即可。
