mac 部署：安装 OpenClaw、onboard、daemon、升级与排障

本章目标：在 macOS 上把 OpenClaw 跑成“长期稳定可用”的常驻服务，并能随时验证、升级、排障。

1) 前置要求

• Node.js：建议 Node ≥ 22（与官方要求对齐）

• 推荐使用 pnpm 或 npm 全局安装 CLI

验证：

node -v
npm -v

2) 安装 OpenClaw CLI

npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

验证：

openclaw --help
openclaw version

3) 首次初始化（onboard）

官方推荐用向导初始化：

openclaw onboard --install-daemon

向导通常会引导你完成：

• workspace 初始化（默认在 ~/.openclaw/workspace）

• 默认 Agent 模型 provider 配置（OpenAI/Anthropic/LiteLLM/Ollama…）

• Skills 安装选择

• 渠道（channels）接入（可跳过）

• 安装 daemon（macOS 一般是 launchd）

不想一次配完：

openclaw onboard --skip-channels --skip-skills --install-daemon

4) 常驻运行与基本健康检查

4.1 查看 daemon 状态

不同版本/安装方式会略有差异，常用的排障手段：

• 先用 CLI 自检：

openclaw doctor
openclaw config list

• 如果你知道它以 launchd 运行，可用：

launchctl list | grep -i claw

4.2 最小可用验证（不依赖 IM 渠道）

用 CLI 直接跑一条消息：

openclaw agent --message "写一个 TypeScript 的 debounce" --thinking high

如果你配置了 web_search / web_fetch / browser 等工具，可单独逐项验证。

5) 模型 Provider 最常见的两种落地

5.1 云端（OpenAI/Anthropic）

核心是把 Key 配到 daemon 能读到的地方（例如环境变量或配置文件）。

示例：

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."

5.2 本地（Ollama）

如果你希望“本地模型也能工具调用”：

brew install ollama
ollama serve
ollama pull llama3.3
export OLLAMA_API_KEY="ollama-local"

然后在 OpenClaw 里把默认模型指到 ollama/<model>。

6) 升级

npm i -g openclaw@latest
# 或 pnpm add -g openclaw@latest
openclaw version

升级后如果插件/配置变更需要重启（视版本而定）。

7) 常见问题与排障

7.1 Node 版本不满足 / CLI 启动失败

• node -v 检查版本

• 确保全局安装目录在 PATH

7.2 daemon 启动但无响应

优先跑：

openclaw doctor

看输出里是否提示：端口冲突、配置损坏、权限不足、provider key 缺失。

7.3 环境变量在终端里有，但 daemon 里没有

这是 macOS 常见坑：launchd 的环境变量与交互 shell 不同。

解决思路（选其一）：

• 用 OpenClaw 的配置系统写入 key（推荐）

• 或者把 key 写入 daemon 的启动环境（不推荐写明文，注意权限）

---

返回目录