一、文档说明本文档面向 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安装 HomebrewmacOS 包管理器推荐若已安装 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自动适配 v24brew 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 全局安装 OpenClawnpm install -g openclaw✅ 验证安装路径ls ~/.npm-global/lib/node_modules/openclaw输出 OpenClaw 相关文件如dist、package.json即安装成功。步骤2OpenClaw 配置文件初始化与修改OpenClaw 核心配置文件为~/.openclaw/openclaw.json需确保语法合法且适配 DeepSeek 模型。2.1 初始化配置目录首次部署mkdir -p ~/.openclaw2.2 备份原有配置若有if [ -f ~/.openclaw/openclaw.json ]; then mkdir -p ~/.openclaw/backup cp ~/.openclaw/openclaw.json ~/.openclaw/backup/openclaw.json.bak fi2.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 // 替换个人生成的此值即可 } } } EOF2.4 配置文件修改说明替换你的DeepSeek API Key从 DeepSeek 控制台 获取格式为sk-xxxx替换你的用户名macOS 用户名可通过whoami命令查看终端执行whoami即可输出生成并打印OpenClaw的tokennode ~/.npm-global/lib/node_modules/openclaw/openclaw.mjs gateway token --print2.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 清理残余进程避免端口冲突# 方法1OpenClaw 官方停止命令 openclaw gateway stop # 方法2强制杀死所有 OpenClaw 进程推荐 pkill -f openclaw # 方法3杀死占用 18789 端口的进程若端口被占用 lsof -i :18789 | grep -v PID | awk {print $2} | xargs kill -9 2/dev/null3.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 控制台生成。五、常见问题排查问题1Node.js 安装失败原因网络问题导致 Homebrew 下载失败解决切换国内源安装 Node.js# 配置 npm 国内源 npm config set registry https://registry.npmmirror.com # 直接通过 npm 安装 Node.js npm install -g n n 24.13.0问题2JSON 语法错误如invalid character :原因配置文件存在格式错误全角字符、多余符号解决直接重新执行步骤2.3 的配置写入命令避免手动修改格式。问题3端口冲突Gateway already running locally原因18789 端口被占用或 OpenClaw 进程未彻底停止解决执行步骤3.1 的进程清理命令或更换启动端口如--port 18788。问题4UI 无对话反馈网关启动正常原因1未指定默认模型agents.defaults.model.primary缺失解决确保配置中包含primary: deepseek/deepseek-chat原因2API Key 无效/过期解决重新从 DeepSeek 控制台生成 Key 并替换配置原因3配置包含冗余字段wizard/messages/commands解决删除冗余字段仅保留步骤2.3 中的核心配置。问题5Docker 容器名称冲突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 stop2. 删除 OpenClaw 核心目录配置数据rm -rf ~/.openclaw3. 删除 OpenClaw 日志文件rm -rf /tmp/openclaw4. 卸载 OpenClaw npm 包npm uninstall -g openclaw5. 清理 Docker 残余若通过 1Panel/Docker 部署过# 列出所有容器 docker ps -a | grep openclaw # 删除 OpenClaw 相关容器替换为实际容器ID docker rm 容器ID # 清理未使用的镜像/卷可选 docker system prune -a6. 验证清理完成# 检查进程无输出即清理成功 ps -ef | grep openclaw | grep -v grep # 检查目录无输出即清理成功 ls ~/.openclaw ls /tmp/openclaw七、注意事项1. 环境配置规范Node.js 版本必须 v24.13.0 及以上低版本会导致 OpenClaw 启动失败npm 全局路径配置后避免EACCES权限报错建议必做配置文件JSON 语法严格仅使用半角符号无注释键名/值必须用双引号包裹。2. 模型使用注意优先选择 DeepSeekAnthropic 模型需国际信用卡充值、合规网络国内用户适配性差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 模型完成对话交互。