OpenClaw for macOS: 完整本地化部署指南（2026.2.6-3 版本）-程序员充电站

一、文档说明

本文档面向 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，跳过此步骤；未安装则执行：

/* by 01022.hk - online tools website : 01022.hk/zh/androidmanifest.html */ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

✅ 验证安装：

/* by 01022.hk - online tools website : 01022.hk/zh/androidmanifest.html */ brew -v

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

步骤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 全局路径（可选，避免权限报错）

# 创建全局目录 mkdir -p ~/.npm-global # 配置 npm 全局路径 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 全局安装 OpenClaw：

npm install -g openclaw

✅ 验证安装路径：

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命令查看（终端执行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 failed→ 检查 DeepSeek API Key 是否有效。

4.2 访问 OpenClaw UI 测试对话

打开浏览器，访问http://127.0.0.1:18789；

在输入框发送测试消息（如「test」或「你好」）；
✅ 收到 DeepSeek 回复 → 部署完全成功；

❌ 无回复：执行以下命令验证 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 控制台生成。

五、常见问题排查

问题1：Node.js 安装失败

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

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

# 配置 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 容器未删除；

解决：

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

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

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

1. 停止所有 OpenClaw 进程

pkill -f openclaw openclaw gateway stop

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

rm -rf ~/.openclaw

3. 删除 OpenClaw 日志文件

rm -rf /tmp/openclaw

4. 卸载 OpenClaw npm 包

npm uninstall -g openclaw

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

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

6. 验证清理完成

# 检查进程（无输出即清理成功） 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 模型完成对话交互。