一、文档说明

本文档面向 macOS 系统用户，从基础环境搭建（Node.js 安装） 到 OpenClaw 完整部署，再到问题排查、残余清理，提供全流程标准化操作，适配 OpenClaw 2026.2.6-3 版本，最终实现 DeepSeek 模型的稳定调用。

二、部署前置条件

1. 系统要求

操作系统：macOS 10.15+（本文以 MacBook Air (M系列/Intel) 为例）
权限：拥有终端管理员权限（可执行 sudo 命令）
网络：能正常访问 DeepSeek API（国内网络直接支持）

2. 预期成果

完成 Node.js 环境搭建（v24.13.0 及以上）；
OpenClaw 网关正常启动，端口 18789 可访问；
OpenClaw UI 能调用 DeepSeek 模型并返回对话结果。

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

OpenClaw 基于 Node.js 运行，需先完成 Node.js 安装与版本验证。

步骤1：安装 Homebrew（macOS 包管理器，推荐）

若已安装 Homebrew，跳过此步骤；未安装则执行：

Bash 复制代码

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

✅ 验证安装：

Bash 复制代码

brew -v

输出 Homebrew 4.x.x 即安装成功。

步骤2：安装 Node.js

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

Bash 复制代码

brew install node

✅ 验证安装与版本：

Bash 复制代码

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

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

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

Bash 复制代码

# 创建全局目录
mkdir -p ~/.npm-global
# 配置 npm 全局路径
npm config set prefix '~/.npm-global'
# 将全局路径加入环境变量（永久生效）
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
# 生效环境变量
source ~/.zshrc

✅ 验证配置：

Bash 复制代码

npm config get prefix

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

四、OpenClaw 完整部署流程

步骤1：安装 OpenClaw 包

通过 npm 全局安装 OpenClaw：

Bash 复制代码

npm install -g openclaw

✅ 验证安装路径：

Bash 复制代码

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

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

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

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

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

Bash 复制代码

mkdir -p ~/.openclaw

2.2 备份原有配置（若有）

Bash 复制代码

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

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

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

Bash 复制代码

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 命令查看（终端执行 whoami 即可输出）；
生成并打印OpenClaw的token

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

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

Bash 复制代码

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

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

2.6 修复配置权限

Bash 复制代码

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

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

步骤3：启动 OpenClaw 网关

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

Bash 复制代码

# 方法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 启动网关（指定端口并强制重载）

Bash 复制代码

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

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

步骤4：验证部署效果

4.1 实时监控运行日志

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

Bash 复制代码

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

无 error/invalid config 关键字 → 运行正常；
若出现 API request failed → 检查 DeepSeek API Key 是否有效。

4.2 访问 OpenClaw UI 测试对话

打开浏览器，访问 http://127.0.0.1:18789；
在输入框发送测试消息（如「test」或「你好」）；
✅ 收到 DeepSeek 回复 → 部署完全成功；

❌ 无回复：执行以下命令验证 API Key 有效性：

Bash 复制代码

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 控制台生成。

五、常见问题排查

问题1：Node.js 安装失败

原因：网络问题导致 Homebrew 下载失败；

解决：切换国内源安装 Node.js：

Bash 复制代码

# 配置 npm 国内源
npm config set registry https://registry.npmmirror.com
# 直接通过 npm 安装 Node.js
npm install -g n
n 24.13.0

问题2：JSON 语法错误（如 `invalid character ':'`）

原因：配置文件存在格式错误（全角字符、多余符号）；
解决：直接重新执行步骤2.3 的配置写入命令，避免手动修改格式。

问题3：端口冲突（`Gateway already running locally`）

原因：18789 端口被占用，或 OpenClaw 进程未彻底停止；
解决：执行步骤3.1 的进程清理命令，或更换启动端口（如 --port 18788）。

问题4：UI 无对话反馈（网关启动正常）

原因1：未指定默认模型（agents.defaults.model.primary 缺失）；

解决：确保配置中包含 "primary": "deepseek/deepseek-chat"；

原因2：API Key 无效/过期；

解决：重新从 DeepSeek 控制台生成 Key 并替换配置；

原因3：配置包含冗余字段（wizard/messages/commands）；

解决：删除冗余字段，仅保留步骤2.3 中的核心配置。

问题5：Docker 容器名称冲突（`container name already in use`）

原因：1Panel 部署的 OpenClaw 容器未删除；

解决：

Bash 复制代码

# 停止冲突容器（替换为实际容器ID/名称）
docker stop 1Panel-openclaw-rt8j
# 删除冲突容器
docker rm 1Panel-openclaw-rt8j

六、OpenClaw 残余内容清理（彻底卸载/重置）

若需重新部署或完全卸载 OpenClaw，执行以下命令清理所有残余文件：

1. 停止所有 OpenClaw 进程

Bash 复制代码

pkill -f openclaw
openclaw gateway stop

2. 删除 OpenClaw 核心目录（配置+数据）

Bash 复制代码

rm -rf ~/.openclaw

3. 删除 OpenClaw 日志文件

Bash 复制代码

rm -rf /tmp/openclaw

4. 卸载 OpenClaw npm 包

Bash 复制代码

npm uninstall -g openclaw

5. 清理 Docker 残余（若通过 1Panel/Docker 部署过）

Bash 复制代码

# 列出所有容器
docker ps -a | grep openclaw
# 删除 OpenClaw 相关容器（替换为实际容器ID）
docker rm 容器ID
# 清理未使用的镜像/卷（可选）
docker system prune -a

6. 验证清理完成

Bash 复制代码

# 检查进程（无输出即清理成功）
ps -ef | grep openclaw | grep -v grep
# 检查目录（无输出即清理成功）
ls ~/.openclaw
ls /tmp/openclaw

七、注意事项

1. 环境配置规范

Node.js 版本：必须 v24.13.0 及以上，低版本会导致 OpenClaw 启动失败；
npm 全局路径：配置后避免 EACCES 权限报错，建议必做；
配置文件：JSON 语法严格，仅使用半角符号，无注释，键名/值必须用双引号包裹。

2. 模型使用注意

优先选择 DeepSeek：Anthropic 模型需国际信用卡充值、合规网络，国内用户适配性差；
DeepSeek API Key 有效期：需确保 Key 未过期，且账号有余额（DeepSeek 提供免费额度）；
模型 ID 不可修改：DeepSeek 必须使用 deepseek-chat，自定义 ID 会导致调用失败。

3. 进程与端口管理

启动前必清进程：避免端口冲突和配置重载失败；
端口占用处理：若 18789 被占用，可更换端口（如 --port 18788），同时修改配置文件中的 port 字段。

4. 权限与网络

终端权限：执行 rm/mkdir 命令时若报错，加 sudo 提升权限；

八、总结

核心流程回顾

搭建基础环境：安装 Homebrew → 安装 Node.js → 配置 npm 全局路径；
部署 OpenClaw：安装包 → 写入合法配置 → 验证语法 → 启动网关；
验证效果：访问 UI 测试对话 → 实时监控日志排查问题；
清理残余：停止进程 → 删除配置/日志/包文件。

关键要点

配置文件是核心：语法错误、字段缺失是部署失败的主要原因；
DeepSeek 适配性最优：国内网络无需额外配置，API Key 易获取；
日志是排查利器：启动后通过 tail -f 实时查看日志，快速定位问题。

通过以上步骤，可实现 OpenClaw 在 macOS 上的标准化部署，且能稳定调用 DeepSeek 模型完成对话交互。

OpenClaw for macOS: 完整本地化部署指南（2026.2.6-3 版本）

一、文档说明

二、部署前置条件

1. 系统要求

2. 预期成果

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

步骤1：安装 Homebrew（macOS 包管理器，推荐）

步骤2：安装 Node.js

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

四、OpenClaw 完整部署流程

步骤1：安装 OpenClaw 包

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

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

2.2 备份原有配置（若有）

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

2.4 配置文件修改说明

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

2.6 修复配置权限

步骤3：启动 OpenClaw 网关

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

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

步骤4：验证部署效果

4.1 实时监控运行日志

4.2 访问 OpenClaw UI 测试对话

五、常见问题排查

问题1：Node.js 安装失败

问题2：JSON 语法错误（如 invalid character ':'）

问题3：端口冲突（Gateway already running locally）

问题4：UI 无对话反馈（网关启动正常）

问题5：Docker 容器名称冲突（container name already in use）

六、OpenClaw 残余内容清理（彻底卸载/重置）

1. 停止所有 OpenClaw 进程

2. 删除 OpenClaw 核心目录（配置+数据）

3. 删除 OpenClaw 日志文件

4. 卸载 OpenClaw npm 包

5. 清理 Docker 残余（若通过 1Panel/Docker 部署过）

6. 验证清理完成

七、注意事项

1. 环境配置规范

2. 模型使用注意

3. 进程与端口管理

4. 权限与网络

八、总结

核心流程回顾

关键要点

问题2：JSON 语法错误（如 `invalid character ':'`）

问题3：端口冲突（`Gateway already running locally`）

问题5：Docker 容器名称冲突（`container name already in use`）