OpenClaw 本地部署指南（Mac 系统）

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

1.1 适用范围 & 核心说明

本手册适用于零编程基础用户，提供完整的 OpenClaw 本地部署步骤。严格按照操作指引执行，通常可在 10 分钟内完成部署。

1.2 系统 & 硬件要求

• 系统版本：macOS 12.0 (Monterey) 及以上，建议升级至最新版本以避免兼容性问题。
• 硬件适配：Intel 芯片、Apple Silicon M1/M2/M3/M4 全系列均支持。
• 磁盘空间：至少预留 2GB 可用空间用于存放依赖环境和配置文件。

1.3 安装前必做检查

1. 网络检查：确保可访问 GitHub 及境外网站，安装过程需拉取仓库资源。
2. 终端权限检查：在「系统设置→隐私与安全性→完全磁盘访问」中开启终端权限，避免写入文件报错。
3. 代理规则检查：若开启 VPN/代理，确保终端流量走代理通道，防止 Git 拉取超时。

1.4 核心注意事项

1. 全程不要使用 sudo执行 npm 安装命令，否则会导致不可逆的权限报错。
2. 所有命令建议直接复制粘贴，避免手动输入拼写错误。
3. Node.js 必须安装 LTS 长期支持版本，禁止使用最新尝鲜版。
4. API 密钥严禁泄露，以免账号被盗刷产生高额费用。
5. 启动服务后对应的终端窗口不能关闭，否则服务将停止。

2. 前置依赖环境安装

2.1 安装 Homebrew 包管理器

Homebrew 是 macOS 专属包管理器，为后续依赖安装的基础。

1. 打开 Mac 终端：启动台→其他→终端，或按下 Command+空格，输入「终端」回车。
2. 复制以下命令，粘贴到终端中执行（使用清华源）：

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

3. 执行过程中选择 1，运用清华源安装。终端提示输入密码时输入开机密码（输入不显示字符，输完回车）。
4. 等待安装完成，出现 Installation successful! 字样即成功。
5. 配置环境变量（Apple Silicon M 系列必须执行）：

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

6. 验证安装：终端输入 brew -v，出现版本号即成功。

2.2 安装 Node.js & npm 运行环境

OpenClaw 基于 Node.js 开发，需安装对应运行环境。

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

brew install node@20

2. 等待安装完成，执行环境变量配置命令：

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

3. 验证安装：分别执行 node -v 和 npm -v，均正常输出版本号即成功。

2.3 安装 Git 环境 & 权限配置

Git 用于拉取 GitHub 上的依赖仓库。

1. 终端执行以下命令安装 Git：

brew install git

2. 验证安装：git --version，出现版本号即成功。
3. 【核心配置】解决 SSH 权限报错，让 Git 优先用 HTTPS 访问 GitHub：

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

4. 【可选配置】Git 用户名和邮箱：

git config --global user.name "你的 GitHub 用户名"
git config --global user.email "你的 GitHub 注册邮箱"

2.4 依赖环境验证

终端一次性执行以下 4 个命令，全部正常输出版本号且无报错，说明前置环境就绪。

brew -v
node -v
npm -v
git --version

3. OpenClaw 核心程序安装

3.1 全局安装 OpenClaw

1. 切换 npm 下载源为国内镜像：

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

2. 确保 Git 使用 HTTPS 访问 GitHub（如未配置）：

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

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

npm install -g openclaw@latest

4. 输入密码后回车进行安装。等待出现 added xxx packages in xxxs 字样，无红色报错即成功。
5. 验证安装：终端执行 openclaw -v，出现版本号即成功。

3.2 初始化配置向导

1. 终端执行初始化命令：

openclaw init

2. 按照向导提示完成配置，可直接回车使用默认值，仅需设置后台访问用户名和密码（推荐 admin / 123456）。
3. 配置完成后，终端出现 Configuration initialized successfully! 字样即成功。

3.3 大模型 API 密钥配置

OpenClaw 基于大模型运行，必须配置 API 密钥。

1. 打开配置文件：

open ~/.openclaw/config.yaml

2. 修改 llm 配置段，以下提供两种方案：

方案 1：阿里云通义千问（国内首选）

llm:
  provider: dashscope
  api_key: "你的通义千问 API 密钥"
  model: "qwen-max"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"

方案 2：OpenAI GPT 方案

llm:
  provider: openai
  api_key: "你的 OpenAI API 密钥"
  model: "gpt-4o"
  base_url: "https://api.openai.com/v1"

3. 保存配置文件并关闭窗口。注意 API 密钥前后不要留多余空格。

3.4 启动服务

1. 终端执行启动命令：

openclaw start

2. 等待启动完成，终端出现 OpenClaw server is running on http://localhost:9000 字样即成功。

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

4.1 终端状态验证

新开一个终端窗口，执行：

openclaw status

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

4.2 网页后台访问验证

1. 打开浏览器，访问 http://localhost:9000（若修改过端口请替换）。
2. 输入第 3 章配置的用户名和密码登录。
3. 进入后台管理主界面说明安装成功。

4.3 功能测试

在后台对话界面输入测试指令（如'帮我写一份 Mac 终端常用命令清单'），大模型正常返回内容说明全流程运行正常。

5. 常见问题与解决方案

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

• 原因：Git 通过 SSH 拉取失败或缺少认证。
• 解决：执行 Git HTTPS 配置命令；清理缓存 npm cache clean --force；重新执行安装命令。

5.2 常见报错 2：command not found

• 原因：环境变量未配置成功。
• 解决：重新执行环境变量配置命令；执行 source ~/.zshrc；重启终端。

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

• 原因：默认 9000 端口被占用或防火墙拦截。
• 解决：停止服务 openclaw stop；修改配置文件中的 port 参数；重启服务；检查防火墙设置。

5.4 常见报错 4：API 密钥配置无效

• 原因：参数错误、密钥无效或网络不通。
• 解决：检查配置文件中 provider 和 base_url 匹配情况；确认密钥有效性；国内用户使用 OpenAI 需确保网络通畅。

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

• 原因：之前使用 sudo 安装导致目录权限异常。
• 解决：修复权限 sudo chown -R $(whoami) ~/.npm；清理缓存；重新安装且不加 sudo。

6. 进阶拓展配置

6.1 接入办公软件

在后台「集成」模块中选择飞书或钉钉，创建企业应用获取 App ID 和 Secret 填入配置即可。

6.2 对接 Ollama 本地大模型

1. 前往 Ollama 官网下载 Mac 版本并安装。
2. 终端拉取模型：ollama pull qwen。
3. 修改配置文件 llm 段：

llm:
  provider: ollama
  model: "qwen"
  base_url: "http://localhost:11434/v1"

4. 保存配置并重启服务。

6.3 开机自启配置

1. 创建开机自启服务：

openclaw service install

2. 取消自启：

openclaw service uninstall

7. 附录

7.1 OpenClaw 常用命令速查表

命令	功能说明
npm install -g openclaw@latest	全局安装 / 升级 OpenClaw
openclaw -v	查看版本号
openclaw init	初始化配置文件
openclaw start	启动服务
openclaw stop	停止服务
openclaw restart	重启服务
openclaw status	查看运行状态
openclaw logs	查看运行日志
open ~/.openclaw/config.yaml	打开核心配置文件

7.2 官方资源链接

• OpenClaw GitHub 仓库：https://github.com/openclaw/openclaw
• Homebrew 官方网站：https://brew.sh/
• 阿里云通义千问 API：https://dashscope.aliyun.com/
• OpenAI API 密钥申请：https://platform.openai.com/api-keys