openclaw小龙虾【Mac电脑版】超详细本地部署手册指南

Openclaw小龙虾【Mac电脑版】本地部署手册指南

（目录）

1. 安装前必读 & 前置准备

1.1 适用范围 & 核心说明

1.2 系统 & 硬件要求

1.3 安装前必做 3 项检查

1.4 全程核心避坑前置提醒

1. 前置依赖环境安装（必装，缺一不可）

2.1 第一步：安装 Homebrew 包管理器

2.2 第二步：安装 Node.js & npm 运行环境

2.2.1 Homebrew 在线安装方式

2.2.2 官网安装包离线安装方式

2.3 第三步：安装 Git 环境 & 权限配置

2.4 依赖环境安装成功验证

1. OpenClaw 核心程序安装（核心步骤）

3.1 安装前预配置（国内镜像 & Git 地址优化）

3.2 第一步：全局安装 OpenClaw 最新版

3.3 第二步：OpenClaw 初始化配置向导

3.4 第三步：大模型 API 密钥核心配置

3.5 第四步：启动 OpenClaw 服务

1. 安装成功验证 & 基础功能测试

4.1 终端命令安装验证

4.2 网页后台访问验证

4.3 小白入门功能测试

1. 视频核心避坑指南 & 高频报错解决方案

5.1 安装全程高频避坑红线

5.2 常见报错 1：npm error code 128 权限报错

5.3 常见报错 2：command not found 命令找不到

5.4 常见报错 3：端口占用 / 无法访问后台

5.5 常见报错 4：API 密钥配置无效 / 调用失败

5.6 常见报错 5：npm 安装权限不足报错

1. 进阶拓展配置（可选，视频拓展内容）

6.1 接入飞书 / 钉钉办公软件

6.2 对接 Ollama 本地大模型（无 API 费用、断网可用）

6.3 开机自启配置

1. 附录

7.1 OpenClaw 常用命令速查表

7.2 官方资源 & 视频链接

第 1 章 安装前必读 & 前置准备

1.1 适用范围 & 核心说明

本手册专为零编程基础的小白打造，全程无跳步，所有操作均有明确指引和截图标注，严格按照步骤操作，10 分钟即可完成 OpenClaw 本地部署。

1.2 系统 & 硬件要求

• 系统版本：MacOS 12.0（Monterey）及以上，低于该版本建议先升级系统，避免兼容性问题
• 硬件适配：Intel 芯片、Apple Silicon M1/M2/M3/M4 全系列芯片均完美适配
• 磁盘空间：至少预留 2GB 可用空间，用于存放依赖环境和配置文件

1.3 安装前必做 3 项检查

1. 网络检查：确保网络可正常访问 GitHub、境外网站，安装过程需拉取 GitHub 仓库资源，网络不通会直接导致安装失败
2. 终端权限检查：打开「系统设置→隐私与安全性→完全磁盘访问」，打开终端的权限开关，避免后续写入文件报错
3. 代理规则检查：若开启 VPN / 代理，确保终端走代理通道，否则会出现 git 拉取仓库超时、失败问题

1.4 全程核心避坑前置提醒（视频重点强调）

1. 全程绝对不要用 sudo执行 npm 安装命令，否则会出现不可逆的权限报错
2. 所有命令建议直接复制粘贴，不要手动输入，避免拼写错误导致安装失败
3. Node.js 必须安装 LTS 长期支持版本，禁止安装最新尝鲜版，否则会出现严重兼容性问题
4. API 密钥严禁泄露给任何人，否则会导致账号被盗刷，产生高额费用
5. 启动 OpenClaw 服务后，对应的终端窗口不能关闭，关闭即停止服务，后台运行方案见第 6 章

第 2 章 前置依赖环境安装（必装，缺一不可）

2.1 第一步：安装 Homebrew 包管理器

Homebrew 是 MacOS 专属的包管理器，是后续安装所有依赖的基础，必须优先安装。

1. 打开 Mac 终端：启动台→其他→终端，或按下Command+空格，输入「终端」回车打开

截图内容：Mac 终端打开后的初始界面，标注启动台打开终端的路径

1. 复制以下安装命令，粘贴到终端中，按下回车执行（运用清华源作为安装）

/bin/zsh -c "$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

截图内容：命令粘贴到终端后的界面，标注回车执行的操作

1. 执行过程中，首先选择1，运用清华源安装，终端会提示输入密码，此处输入你的 Mac 开机密码（输入时终端不会显示字符，输完直接回车即可）

----注意如果之前有安装过，那么需要可以自行选择删除或保留，系统会自动备份

截图内容：终端提示输入密码的界面，标注密码输入的注意事项

1. 等待安装完成，安装时长取决于网络速度，一般 3-10 分钟，终端出现==> Installation successful!字样，即安装成功

截图内容：Homebrew 安装成功的终端界面，圈出成功提示字样

-再次输入密码，回车。

截图内容：选择阿里国内源进行安装

如果以上步骤没有报错，那么可以直接跳转到git安装

1. 执行环境变量配置命令（Apple Silicon M 系列芯片必须执行，Intel 芯片可选）

M 系列芯片执行：

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

eval "$(/opt/homebrew/bin/brew shellenv)"Intel 芯片执行：

Intel 芯片执行：

echo 'eval "$(/usr/local/bin/brew shellenv)"' >> ~/.zprofile

eval "$(/usr/local/bin/brew shellenv)"

输入之后应该出现，环境变量命令执行后的终端界面

验证安装成功：终端输入brew -v，回车后出现版本号，即安装成功

brew -v执行后输出版本号的界面，标注成功标识

2.2 第二步：安装 Node.js & npm 运行环境

OpenClaw 基于 Node.js 开发，必须安装对应运行环境，本手册选用视频推荐的稳定 LTS 版本 node@20。

1. 终端执行以下命令，通过 Homebrew 安装 Node.js LTS 版本

brew install node@20

观察安装命令执行后的终端界面，标注安装进度

1. 等待安装完成，执行环境变量配置命令，让系统识别 node 和 npm 命令

echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc

source ~/.zshrc

验证安装成功：终端分别执行以下 2 个命令，均正常输出版本号，即安装成功

node -v

npm -v

两个命令执行后均输出版本号的界面，标注成功标识

避坑提示：若执行命令提示command not found，重新执行上述环境变量配置命令，或重启终端再次验证。

关闭终端，重新打开。

2.3 如无报错 第二步：安装 Git 环境 & 权限配置

Git 用于拉取 GitHub 上的依赖仓库，也是解决 npm error code 128 报错的核心环节。

1. 终端执行以下命令，通过 Homebrew 安装 Git

brew install git

截图内容：Git 安装命令执行后的终端界面

1. 等待安装完成，验证安装成功：

git --version

回车后出现版本号，即安装成功（成功之后无需进行一下步骤）

【核心避坑配置】彻底解决 SSH 权限报错（code128），终端执行以下 2 条命令，让 Git 优先用 HTTPS 代替 SSH 访问 GitHub

git config --global url."https://github.com/".insteadOf "ssh://[email protected]/"

git config --global url."https://github.com/".insteadOf "[email protected]:"

两条配置命令执行后的终端界面，无报错即为成功

【可选配置】Git 用户名和邮箱配置，避免后续操作报错

git config --global user.name "你的GitHub用户名"

git config --global user.email "你的GitHub注册邮箱"

无 GitHub 账号可前往https://github.com/免费注册。

2.4 依赖环境安装成功验证

终端一次性执行以下 4 个命令，全部正常输出版本号、无报错，说明前置环境全部就绪，可进入核心安装环节。

brew -v

node -v

npm -v

git --version

第三步：安装Node.js

来到Node.js的官方下载页面，点击”macOS安装程序”按钮

下载完成后，打开安装包，同意用户协议

输入开机密码，安装完成并关闭

第 3 章 OpenClaw 核心程序安装（核心步骤）

3.1 第一步：全局安装 OpenClaw 最新版

1.先回到终端，输入npm config set registry http://registry.npmmirror,com

目的是把npm的下载源切换到国内镜像，安装依赖会快一些。

2.输入git config --global url."https://github.com/".insteadOf ssh://[email protected]/

让Git在访问GitHub时，自动把SSH地址改为HTTPS地址（避免产生配置问题）

3. 终端执行以下安装命令，全局安装 OpenClaw 最新稳定版

npm install -g openclaw@latest

截图内容：安装命令粘贴到终端后的界面，标注回车执行操作

输入密码后，回车进行安装

1. 【红线避坑】绝对不要加 sudo！加 sudo 会导致后续权限报错，无法正常启动服务
2. 等待安装完成，安装时长取决于网络速度，一般 2-5 分钟，终端出现added xxx packages in xxxs字样，无红色报错，即安装成功

截图内容：OpenClaw 安装成功的终端界面，圈出无红色报错、安装成功的提示

3.验证安装：终端执行openclaw -v，出现版本号，即安装成功

openclaw -v执行后输出版本号的界面

3.2 OpenClaw 初始化配置向导

1. 终端执行初始化命令，生成配置文件，启动配置向导

openclaw init

查看init 命令执行后的终端界面

1. 按照向导提示完成配置，小白全程可直接回车使用默认配置，仅需设置用户名密码，步骤如下：
   • 配置文件存放路径：直接回车，使用默认路径即可
   • 日志级别选择：直接回车，使用默认的 info 级别即可
   • 服务端口配置：默认 9000，直接回车即可；若 9000 端口被占用，可改为 9001、9002 等未占用端口
   • 后台访问用户名 & 密码：设置简单好记的账号密码，小白推荐用户名admin，密码123456，避免后续忘记
2. 配置完成后，终端出现✅ Configuration initialized successfully!字样，说明初始化成功

3.3 第三步：大模型 API 密钥核心配置

OpenClaw 基于大模型运行，必须配置大模型 API 密钥，否则无法使用，以下提供 2 种适配方案，小白优先选择国内方案，访问更稳定。

1. 终端执行以下命令，打开 OpenClaw 核心配置文件

open ~/.openclaw/config.yaml

1. 【方案 1 国内用户首选 阿里云通义千问】国内访问稳定，有免费额度，新手零门槛

找到文件中的llm配置段，修改为以下内容：

yaml

llm:

  provider: dashscope

  api_key: "你的通义千问API密钥"

  model: "qwen-max"

  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"

【方案 2 OpenAI GPT 方案】适合有 OpenAI 账号的用户

yaml

llm:

  provider: openai

  api_key: "你的OpenAI API密钥"

  model: "gpt-4o"

  base_url: https://api.openai.com/v1

1. API 密钥获取方法：
   • 通义千问密钥：登录阿里云百炼https://dashscope.aliyun.com/，开通服务后创建 API 密钥，免费额度足够新手使用
   • OpenAI 密钥：登录https://platform.openai.com/api-keys，创建新的密钥并复制

1. 配置完成后，按下Command+S保存配置文件，关闭窗口即可

【避坑提醒】API 密钥前后不要留多余空格，否则会导致配置失效；严禁将密钥泄露给他人。

3.4 第四步：启动 OpenClaw 服务

1. 终端执行启动命令，启动 OpenClaw 后台服务

openclaw start

1. 等待启动完成，终端出现✅ OpenClaw server is running on http://localhost:9000字样，说明启动成功
2. 【避坑提醒】启动服务后，该终端窗口不能关闭，关闭窗口会直接停止服务，后台常驻方案见第 6 章。

第 4 章 安装成功验证 & 基础功能测试

4.1 终端命令安装验证

新开一个终端窗口，执行以下命令，查看 OpenClaw 运行状态：

openclaw status

终端显示running状态，说明服务正常运行。

4.2 网页后台访问验证

1. 打开 Chrome、Safari 等任意浏览器，在地址栏输入：http://localhost:9000（若修改过端口，替换为对应端口），回车访问
2. 进入登录界面，输入第 3 章配置的用户名和密码，点击登录
3. 成功登录后，进入 OpenClaw 后台管理主界面，说明安装完全成功

4.3 小白入门功能测试

1. 在后台的对话界面，输入测试指令：“帮我写一份 Mac 终端常用命令清单，标注每个命令的作用”，点击发送
2. 大模型正常返回内容，说明 API 密钥配置正确，OpenClaw 全流程正常运行

第 5 章 视频核心避坑指南 & 高频报错解决方案

5.1 安装全程高频避坑红线

1. 禁止用 sudo 执行 npm 安装命令，否则会出现权限不足、无法写入文件的报错
2. 网络必须可正常访问 GitHub，否则会出现依赖拉取失败，建议开全局代理或配置终端代理
3. Node.js 必须用 LTS 版本，禁止用尝鲜版，本手册推荐 node@20 为验证的稳定版本
4. 配置文件中，provider、model、base_url、api_key 四个参数必须一一对应，否则会出现调用失败
5. 不要泄露 API 密钥，避免账号被盗刷产生高额费用

5.2 常见报错 1：npm error code 128 权限报错

• 报错原因：Git 通过 SSH 拉取 GitHub 仓库失败，缺少 SSH 密钥认证，网络无法正常访问 SSH 仓库
• 解决方案：
  1. 执行第 2.3 章的 Git 配置命令，改用 HTTPS 访问 GitHub
  2. 清理 npm 缓存：npm cache clean --force
  3. 重新执行安装命令：npm install -g openclaw@latest
  4. 若仍报错，检查网络是否可正常访问 GitHub，确保代理规则正常

5.3 常见报错 2：command not found 命令找不到

• 报错原因：对应软件的环境变量未配置成功，系统无法识别命令
• 解决方案：
  1. 重新执行对应软件的环境变量配置命令
  2. 执行source ~/.zshrc刷新环境变量
  3. 重启终端，重新执行版本验证命令
  4. 若仍无效，用 brew 卸载对应软件后重新安装

5.4 常见报错 3：端口占用 / 无法访问后台

• 报错原因：默认 9000 端口被其他程序占用，或 Mac 防火墙拦截了访问
• 解决方案：
  1. 先停止服务：openclaw stop
  2. 打开配置文件：open ~/.openclaw/config.yaml
  3. 修改port参数，改为 9001、9002 等未被占用的端口
  4. 保存配置，重新启动服务：openclaw start
  5. 浏览器用新端口访问，同时检查 Mac 防火墙，允许终端的网络访问权限

5.5 常见报错 4：API 密钥配置无效 / 调用失败

• 报错原因：配置参数错误、密钥无效、网络无法访问大模型接口、账号无可用额度
• 解决方案：
  1. 检查配置文件中 llm 段的四个参数，确保 provider 和 base_url 完全匹配，无多余空格
  2. 检查 API 密钥是否正确，账号是否有可用调用额度
  3. 国内用户使用 OpenAI 需确保网络可正常访问接口，否则改用通义千问等国内大模型
  4. 重启 OpenClaw 服务，让新配置生效

5.6 常见报错 5：npm 安装权限不足 EACCES: permission denied

• 报错原因：之前用 sudo 安装过 npm 包，导致 npm 目录权限异常
• 解决方案：
  1. 执行以下命令修复 npm 目录权限

sudo chown -R $(whoami) ~/.npm

sudo chown -R $(whoami) /usr/local/lib/node_modules

1. 清理 npm 缓存：npm cache clean --force
2. 重新执行安装命令，禁止加 sudo

第 6 章 进阶拓展配置（可选）

6.1 接入飞书 / 钉钉等办公软件

1. 打开 OpenClaw 后台，进入「集成」模块，选择「飞书」/「钉钉」
2. 按照页面指引，在对应平台创建企业应用，获取 App ID、App Secret 等参数
3. 将参数填写到 OpenClaw 配置界面，保存后重启服务
4. 配置完成后，即可在飞书 / 钉钉内直接和 OpenClaw 对话，实现办公自动化

6.2 对接 Ollama 本地大模型（无 API 费用、断网可用）

1. 前往 Ollama 官网https://ollama.com/，下载 Mac 版本安装包，完成安装
2. 终端执行命令，拉取本地大模型（示例为通义千问，也可替换为 llama3 等其他模型）

ollama pull qwen

1. 打开 OpenClaw 配置文件，修改 llm 配置段为以下内容：

yaml

llm:

  provider: ollama

  model: "qwen"

  base_url: http://localhost:11434/v1

1. 保存配置，重启 OpenClaw 服务，即可使用本地大模型，无需联网、无 API 调用费用

6.3 开机自启配置

无需每次开机都手动执行启动命令，配置后 Mac 开机自动启动 OpenClaw 服务：

1. 终端执行以下命令，创建开机自启服务

openclaw service install

1. 终端出现✅ Service installed successfully字样，即配置成功
2. 取消开机自启命令：openclaw service uninstall

第 7 章 附录

7.1 OpenClaw 常用命令速查表

7.2 官方资源 & 视频链接

• 对应 B 站指导视频：https://www.bilibili.com/video/BV1t4Psz1EmW/
• OpenClaw 官方 GitHub 仓库：https://github.com/openclaw/openclaw
• Homebrew 官方网站：https://brew.sh/
• 阿里云通义千问 API 申请：https://dashscope.aliyun.com/
• OpenAI API 密钥申请：https://platform.openai.com/api-keys