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

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 常用命令速查表

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