OpenClaw macOS Sequoia M1 Pro 架构安装指南

适用环境：macOS 15 (Sequoia) · Apple Silicon (M1/M2/M3) · Node.js 通过 nvm 管理

前置要求

工具	版本要求	说明
macOS	15+	Sequoia
Homebrew	任意	安装脚本依赖
nvm	任意	Node.js 版本管理
Node.js	v22+	通过 nvm 切换

OpenClaw 要求 Node.js v22+。若系统默认版本较低，必须在安装前切换。

一、卸载旧版本

全新安装可跳过此节。

1. 切换到 Node v22 并卸载 npm 包

source ~/.nvm/nvm.sh && nvm use 22 npm uninstall -g openclaw

2. 删除配置目录

rm -rf ~/.openclaw

3. 清理 ~/.zshrc

删除以下行（若存在）：

# OpenClaw Completion source "/Users/<用户名>/.openclaw/completions/openclaw.zsh"

二、安装

1. 切换 Node.js 到 v22

source ~/.nvm/nvm.sh && nvm use 22

验证：

node --version # v22.x.x
npm --version # 10.x.x

2. 执行官方安装脚本

curl -fsSL https://openclaw.ai/install.sh | bash

安装成功后末尾会显示：

🦞 OpenClaw installed successfully (2026.x.x)!

注意：在非交互式终端中运行时，脚本末尾可能出现 Gateway 启动超时或 /dev/tty 报错，属正常现象，不影响安装结果，后续手动启动 Gateway 即可。

3. 验证二进制文件

which openclaw # ~/.nvm/versions/node/v22.x.x/bin/openclaw
openclaw --version # 2026.x.x

三、配置 Claude API Key

编辑 ~/.openclaw/openclaw.json，在 JSON 根层级添加 env 字段：

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-api03-..."
  },
  "agents": { ... },
  "gateway": { ... }
}

设置目录和文件权限：

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

四、启动 Gateway 服务

Gateway 是 OpenClaw 的后台核心服务，需要以 LaunchAgent 形式常驻运行。

1. 安装并启动

openclaw gateway install
openclaw gateway start

若提示已安装，使用 --force 重装：

2. 验证服务状态

openclaw gateway status

正常输出包含：

Runtime: running (pid xxxxx)
RPC probe: ok
Listening: 127.0.0.1:18789

五、配置 Shell 补全

# 生成补全文件
openclaw completion --write-state

# 添加到 ~/.zshrc
echo '' >> ~/.zshrc
echo '# OpenClaw Completion' >> ~/.zshrc
echo 'source "$HOME/.openclaw/completions/openclaw.zsh"' >> ~/.zshrc

# 重载
source ~/.zshrc

六、验证整体状态

openclaw status

正常输出关键字段：

Gateway │ reachable · auth token
Gateway service │ LaunchAgent installed · running
Sessions │ default claude-opus-4-6 (200k ctx)

七、访问 Dashboard

正确方式——使用命令行打开，会自动携带认证 token：

openclaw dashboard

该命令会在浏览器中打开 http://127.0.0.1:18789/#token=<your-token> 并复制到剪贴板。

不要直接在浏览器地址栏输入 http://127.0.0.1:18789/，会因缺少 token 触发认证失败锁定（too many failed authentication attempts）。

解除锁定（若已触发）：

openclaw gateway restart
openclaw dashboard # 重新用命令打开

八、故障排查

openclaw: command not found

nvm 未激活或版本未切换：

source ~/.nvm/nvm.sh && nvm use 22

建议在 ~/.zshrc 的 nvm 初始化代码之后加一行：

nvm use 22 --silent

Gateway 无法连接

openclaw gateway restart
openclaw status

查看实时日志

openclaw logs --follow

运行诊断

openclaw doctor

九、文件目录结构

npm 包（程序本体）

~/.nvm/versions/node/v22.12.0/
├── bin/
│   └── openclaw # 可执行入口（symlink）
└── lib/node_modules/openclaw/
    ├── openclaw.mjs # 主入口脚本
    ├── dist/ # 编译产物
    ├── assets/ # 静态资源
    ├── extensions/ # 扩展
    ├── skills/ # 内置 skills
    ├── docs/ # 文档
    ├── package.json
    └── CHANGELOG.md

配置与数据目录

~/.openclaw/
├── openclaw.json # 主配置文件（API Key、Gateway 设置等）
├── openclaw.json.bak # 配置文件自动备份
├── update-check.json # 版本更新检查缓存
│   ├── agents/
│   │   └── main/
│   │       └── sessions/
│   │           ├── sessions.json # 会话索引
│   │           └── <uuid>.jsonl # 会话历史记录
│   ├── canvas/
│   │   └── index.html # Canvas UI 页面
│   ├── completions/ # Shell 补全脚本
│   │   ├── openclaw.zsh
│   │   ├── openclaw.bash
│   │   ├── openclaw.fish
│   │   └── openclaw.ps1
│   ├── cron/
│   │   ├── jobs.json # 定时任务配置
│   │   └── jobs.json.bak
│   ├── devices/
│   │   ├── paired.json # 已配对设备列表
│   │   └── pending.json # 待配对设备
│   ├── identity/
│   │   ├── device.json # 本机设备身份信息
│   │   └── device-auth.json # 设备认证凭据
│   ├── logs/
│   │   ├── gateway.log # Gateway 标准输出日志
│   │   ├── gateway.err.log # Gateway 错误日志
│   │   └── config-audit.jsonl # 配置变更审计日志
│   ├── memory/ # Agent 全局记忆（插件）
│   └── workspace/ # Agent 默认工作区
├── .git/ # 工作区 Git 仓库
├── .openclaw/
│   └── workspace-state.json # 工作区状态
├── memory/
│   └── 2026-03-01.md # 按日期存储的记忆文件
├── AGENTS.md # Agent 行为配置
├── HEARTBEAT.md # 心跳任务配置
├── IDENTITY.md # Agent 身份定义
├── SOUL.md # Agent 性格/风格设定
├── TOOLS.md # 可用工具说明
└── USER.md # 用户信息配置

系统服务文件

~/Library/LaunchAgents/
└── ai.openclaw.gateway.plist # macOS LaunchAgent 服务定义（开机自启）

Shell 配置（~/.zshrc 相关条目）

# OpenClaw Completion
source "$HOME/.openclaw/completions/openclaw.zsh"

常用命令速查

操作	命令
查看版本	`openclaw --version`
查看状态	`openclaw status`
打开控制台	`openclaw dashboard`
启动 Gateway	`openclaw gateway start`
停止 Gateway	`openclaw gateway stop`
重启 Gateway	`openclaw gateway restart`
查看服务状态	`openclaw gateway status`
实时日志	`openclaw logs --follow`
运行诊断	`openclaw doctor`

OpenClaw v2026.2.26 · macOS 15.7.4 (arm64) · 2026-03-01

OpenClaw macOS Sequoia M1 Pro 架构安装指南