OpenClaw 中文教程站

1. 环境要求

在开始安装之前，请确保你的 Mac 满足以下条件：

操作系统：macOS 11.0 (Big Sur) 或更高版本
Node.js：版本 18.0 或更高（推荐 LTS 版本）
内存：至少 4GB RAM（推荐 8GB+）
磁盘空间：至少 1GB 可用空间
命令行工具：已安装 Xcode Command Line Tools

💡 推荐方式：macOS 用户强烈建议使用 Homebrew 管理依赖，这是 Mac 上最优雅的包管理方式。

2. 安装 Homebrew（推荐）

Homebrew 是 macOS 上最流行的包管理器，让安装软件变得简单优雅。

步骤 2.1：安装 Homebrew

打开终端（Terminal），运行以下命令：

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

安装过程中需要输入你的 Mac 密码（输入时不会显示字符）。

步骤 2.2：配置环境变量

对于 Apple Silicon Mac（M1/M2/M3），需要将 Homebrew 添加到 PATH：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile eval "$(/opt/homebrew/bin/brew shellenv)"

对于 Intel Mac，通常不需要额外配置。

步骤 2.3：验证安装

brew --version

如果显示版本号，说明 Homebrew 安装成功。

3. 安装 Node.js

使用 Homebrew 安装 Node.js 是最推荐的方式。

步骤 3.1：安装 Node.js

brew install node

这会安装最新 LTS 版本的 Node.js 和 npm。

步骤 3.2：验证安装

node --version npm --version

应该显示类似 v20.x.x 和 10.x.x 的版本号。

⚠️ 注意：如果你之前通过其他方式安装了 Node.js，可能会遇到版本冲突。建议使用 brew link --overwrite node 强制使用 Homebrew 版本。

替代方案：使用 nvm（Node 版本管理器）

如果你需要在多个 Node.js 版本之间切换，可以安装 nvm：

brew install nvm # 配置 nvm echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc source ~/.zshrc # 安装并使用 Node.js 20 nvm install 20 nvm use 20

4. 安装 OpenClaw

Node.js 安装完成后，使用 npm 全局安装 OpenClaw CLI。

步骤 4.1：安装 OpenClaw

npm install -g openclaw

如果你遇到权限问题，可以尝试：

sudo npm install -g openclaw

步骤 4.2：验证安装

openclaw --version

如果显示版本号（如 1.x.x），说明安装成功！

5. 首次配置

步骤 5.1：创建工作目录

mkdir ~/openclaw-workspace cd ~/openclaw-workspace

步骤 5.2：初始化配置

openclaw init

这会创建以下文件结构：

~/openclaw-workspace/ ├── openclaw.json      # 主配置文件 ├── .env              # 环境变量（API 密钥） ├── .gitignore        # Git 忽略文件 ├── skills/           # Skill 目录 │   └── example/      # 示例 Skill └── memory/           # 记忆目录

步骤 5.3：配置 AI 模型

编辑 .env 文件（可以使用 nano、vim 或 VS Code）：

code .env

添加你的 API 密钥：

# Kimi API（推荐国内用户） KIMI_API_KEY=your_kimi_api_key_here # 或 OpenAI API OPENAI_API_KEY=your_openai_api_key_here # 或 Anthropic API ANTHROPIC_API_KEY=your_anthropic_api_key_here # 其他可选配置 OPENAI_BASE_URL=https://api.openai.com/v1  # 如果使用代理

💡 获取 API 密钥：
- Kimi：platform.moonshot.cn（国内用户推荐）
- OpenAI：platform.openai.com
- Anthropic：console.anthropic.com

6. 验证安装

完成配置后，启动 OpenClaw 验证一切正常：

openclaw gateway start

你应该看到类似以下的输出：

🦞 OpenClaw Gateway ✓ Gateway started on http://localhost:3000 ✓ WebSocket ready ✓ Connected to 1 model provider ✓ Memory initialized

打开浏览器访问 http://localhost:3000，你应该能看到 OpenClaw Web 界面。

按 Ctrl + C 停止服务。

7. 常见问题

问题 1：Command Line Tools 未安装

症状：安装 Homebrew 或某些包时提示需要 Xcode Command Line Tools。

解决：运行以下命令安装

xcode-select --install

问题 2：权限被拒绝（Permission denied）

原因：macOS 的 SIP 或文件权限限制。

解决：

使用 sudo 运行命令（不推荐长期使用）
修改 npm 全局安装目录权限：

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

问题 3：Apple Silicon (M1/M2/M3) 兼容性问题

症状：某些包安装失败或运行时报错。

解决：确保使用的是 ARM64 原生版本的 Node.js

# 检查 Node.js 架构 node -p "process.arch" # 应该输出 'arm64'，如果是 'x64' 说明运行在 Rosetta 下 # 使用 Homebrew 重新安装原生版本 brew reinstall node

问题 4：端口被占用

症状：启动时提示 "Port 3000 is already in use"。

解决：

# 查找占用 3000 端口的进程 lsof -ti:3000 # 终止该进程 kill -9 $(lsof -ti:3000) # 或使用其他端口启动 openclaw gateway start --port 3001

问题 5：Firewall 阻止连接

症状：启动后无法通过局域网访问。

解决：在系统设置中允许 OpenClaw 通过防火墙，或暂时关闭防火墙测试。

下一步

恭喜！你已经在 macOS 上成功安装并运行了 OpenClaw。接下来可以：

🎉 安装完成！如果在安装过程中遇到其他问题，欢迎在社区提问或在 GitHub 提交 Issue。