一.基础环境搭建（Node.js安装）

步骤1：安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" 海外官方原版安装脚本
/bin/zsh -c "$(curl -fsSL https://gitee.com/huwei1024/HomebrewCN/raw/master/Homebrew.sh)"国内镜像安装脚本（本次选择的命令是这个）

验证安装

brew -v

输出版本号即安装成功
遇到问题：

brew -v
zsh: command not found: brew
/opt/homebrew/bin/brew -v
Homebrew >=4.3.0 (shallow or no git repository)
fatal: detected dubious ownership in repository at '/opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-core'
To add an exception for this directory, call:

	git config --global --add safe.directory /opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-core
Homebrew/homebrew-core (no Git repository)
fatal: detected dubious ownership in repository at '/opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-cask'
To add an exception for this directory, call:

	git config --global --add safe.directory /opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-cask
Homebrew/homebrew-cask (no Git repository)

1. 第一个问题输入brew -v返回command not found但输入/opt/homebrew/bin/brew -v可以返回版本，通常是因为环境变量未配置通过手动添加环境变量可解决。

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

2. 后面的提示是Git安全机制拦截：Homebrew基于Git，而我的Mac上Git检测到Homebrew的核心仓库目录（/opt/homebrew/...）的所有权可能存在可疑（通常是因为安装脚本使用了sudo或其他用户权限运行，导致目录所有者不是当前登录用户），因此拒绝加载Git仓库信息，进而导致（brew）命令无法完整初始化。因此需要将报错中提到的两个目录添加为Git的“安全目录”。通过以下两条命令

   git config --global --add safe.directory /opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-core
   git config --global --add safe.directory /opt/homebrew/Homebrew/Library/Taps/homebrew/homebrew-cask
   

步骤2：安装 Node.js

通过 Homebrew 安装稳定版 Node.js（自动适配 v24+）：

brew install node

验证安装与版本

# 查看 Node.js 版本
node -v
# 查看 npm 版本（Node.js 自带）
npm -v

输出node v24.13.0及以上、npm 10.x.x即符合要求；
若版本过低，执行brew upgrade node升级。

步骤3：配置 npm 全局路径（可选，避免权限报错）

# 创建全局目录
# 作用：在用户主目录下创建一个专门用于存放全局npm包的文件夹
# 优点：完全属于当前用户，不需要root权限即可写入
mkdir -p ~/.npm-global
# 配置 npm 全局路径，以后安装全局包时，存放到~/.npm-global目录而不是/usr/local
npm config set prefix '~/.npm-global'
# 将全局路径加入环境变量（永久生效）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
# 生效环境变量
source ~/.zshrc

验证配置：

npm config get prefix

输出~/.npm-global即配置成功。

二.OpenClaw安装部署

步骤1：安装 OpenClaw 包

将 npm 的下载源（Registry）切换到了 npmmirror（原淘宝 npm 镜像）。这是目前国内开发者最常用、速度最快的 npm 镜像源，相比官方源国内网络环境下，安装包的速度能提升，避免npm install时出现的超时或连接重制错误，同时该镜像与官方源保持分钟级同步，不用担心包版本过旧。

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

验证配置：

npm config get registry

输出https://registry.npmmirror.com/，确认无误。

让Git在访问GitHub时自动把SSH地址改成HTTPS地址，主要有以下几个原因：

• 网络兼容性：某些网络环境ssh端口可能被墙拦截或限速，https端口更加稳定不易阻断；
• 公开仓库，使用https可以直接克隆，无需配置ssh key；

git config --global url."https://github.com/".insteadOf ssh://git@github.com/

验证配置：

git config --global --list | grep -i insteadOf

输出url.https://github.com/.insteadof=ssh://git@github.com/

通过npm全局安装OpenClaw:

sudo npm install -g openclaw@latest

验证安装路径：

ls ~/.npm-global/lib/node_modules/openclaw

输出OpenClaw相关文件（如dist、package.json）即安装成功。

步骤2：OpenClaw 配置文件初始化与修改

OpenClaw核心配置文件为~/.openclaw/openclaw.json，需确保语法合法且适配DeepSeek模型。

2.1 初始化配置目录（首次部署）

mkdir -p ~/.openclaw

2.2备份原有配置（若有）

if [ -f ~/.openclaw/openclaw.json ]; then
  mkdir -p ~/.openclaw/backup
  cp ~/.openclaw/openclaw.json ~/.openclaw/backup/openclaw.json.bak
fi

2.3 写入适配 DeepSeek 的无错配置（核心）

执行以下命令，直接写入预验证的合法配置（替换占位符为真实信息）：

cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "meta": {
    "lastTouchedVersion": "2026.2.6-3",
    "lastTouchedAt": "2026-02-08T07:43:20.228Z"
  },
  "models": {
    "mode": "merge",
    "providers": {
      "deepseek": {
        "baseUrl": "https://api.deepseek.com/v1",
        "apiKey": "你的DeepSeek API Key", // 替换为真实Key（格式：sk-xxxx）
        "api": "openai-completions",
        "models": [
          {
            "id": "deepseek-chat",
            "name": "DeepSeek Chat",
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 8192,
            "reasoning": false
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "workspace": "/Users/你的用户名/.openclaw/workspace", // 替换为实际用户名（如 zhufeige）
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "model": {
        "primary": "deepseek/deepseek-chat" // 指定默认调用 DeepSeek 模型
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "39769ded65eac493eceeb0fb6a543fb48ed4fce3f1166bf5" // 替换个人生成的此值即可
    }
  }
}
EOF

2.4 配置文件修改说明

• 替换你的DeepSeek API Key：从DeepSeek控制台获取，格式为sk-xxxx；
• 替换你的用户名：macOS用户名可通过whoami命令查看；
• 生成并打印OPenClaw的token

node ~/.npm-global/lib/node_modules/openclaw/openclaw.mjs gateway token --print

2.5 配置语法验证（必做，避免启动报错）

node -e "JSON.parse(require('fs').readFileSync('/Users/$(whoami)/.openclaw/openclaw.json', 'utf8'))"

• ✅ 终端无任何输出 → 语法完全正确；
• ❌ 若报错：检查是否有全角字符（如：/，）、多余/缺失的 {}/,/"。

2.6 修复配置权限

node ~/.npm-global/lib/node_modules/openclaw/openclaw.mjs doctor --fix

输出无Config validation failed即权限修复成功。

步骤3：启动 OpenClaw 网关

3.1 清理残余进程（避免端口冲突）

# 方法1：OpenClaw 官方停止命令
openclaw gateway stop

# 方法2：强制杀死所有 OpenClaw 进程（推荐）
pkill -f openclaw

# 方法3：杀死占用 18789 端口的进程（若端口被占用）
lsof -i :18789 | grep -v PID | awk '{print $2}' | xargs kill -9 2>/dev/null

3.2 启动网关（指定端口并强制重载）

node ~/.npm-global/lib/node_modules/openclaw/openclaw.mjs gateway --port 18789 --force

终端输出一下内容即启动成功：

步骤4：验证部署效果

4.1 实时监控运行日志

打开新终端窗口，执行以下命令跟踪日志（排查问题关键）：

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

• 无error/invalid config关键字即为运行正常
• 若出现API request faild，检查DeepSeek API Key是否有效。

4.2 访问 OpenClaw UI 测试对话

1. 打开浏览器，访问http://127.0.0.1:18789；
2. 在输入框发送测试消息（如「test」或「你好」）；
3. ✅ 收到 DeepSeek 回复 → 部署完全成功；
4. ❌ 无回复：执行以下命令验证 API Key 有效性：

   curl -s -X POST https://api.deepseek.com/v1/chat/completions \
     -H "Authorization: Bearer 你的DeepSeek API Key" \
     -H "Content-Type: application/json" \
     -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"test"}]}'
   

   • 输出包括"content"字段→ API Key 有效，重启网关即可；
   • 输出Unauthorized→ API Key 无效，重新从 DeepSeek 控制台生成。