📦 第一部分：环境准备

1.1 安装 Homebrew（Mac 包管理器）

打开终端（Command + 空格 → 输入”终端”），执行以下命令：

bash

/bin/zsh -c “$(curl -fsSL https://gitee.com/cunkai/HomebrewCN/raw/master/Homebrew.sh)"

  • 按提示选择下载源（推荐选 1）
  • 输入开机密码（输入时不显示，正常现象）
  • 等待安装完成

验证安装：

bash

brew –version

1.2 安装 Node.js

bash

brew install node@22

验证安装：

bash

node --version   # 应显示 v22.x.x
npm --version    # 应显示 10.x.x

1.3 配置国内镜像加速（提升下载速度）

bash

npm config set registry https://registry.npmmirror.com

🚀 第二部分：安装 OpenClaw

2.1 全局安装 OpenClaw

bash

npm install -g openclaw@latest

等待安装完成（约 1-3 分钟）

验证安装：

bash

openclaw –version # 应显示 2026.x.x

⚙️ 第三部分：初始化配置（交互式问答）

运行初始化命令：

bash

openclaw onboard

3.1 安全警告

text

◆  I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
│  ○ Yes / ● No

操作： 按 ↓ 键选择 Yes，按回车

3.2 配置模式选择

text

◆  Onboarding mode
│  ● QuickStart (Configure core features: AI models, channels, gateway)
│  ○ Advanced

操作： 保持选中 QuickStart，按回车

3.3 AI 模型提供商选择

text

◆  AI model provider
│  ● Alibaba Cloud Model Studio (China-friendly, coding-optimized)
│  ○ OpenAI
│  ○ Anthropic
│  ○ DeepSeek
│  ○ Ollama (local)
│  ○ Skip for now

操作：

  • 如果有阿里云账号 → 选 Alibaba Cloud Model Studio
  • 如果没有 → 按 ↓ 选 Skip for now，按回车

3.4 API Key 存储方式（如果选择了阿里云）

text

◆  How do you want to provide this API key?
│  ● Paste API key now (Stores the key directly in OpenClaw config)
│  ○ Use external secret provider

操作： 保持选中第一项，按回车

3.5 输入 API Key（如果选择了阿里云）

text

Enter Alibaba Cloud Model Studio Coding Plan API key (China):

操作：

  • 粘贴 API Key（格式：sk-xxxxxxxx），按回车
  • 如果没有 API Key，按 Ctrl + C 退出，或重新选择 Skip for now

3.6 搜索引擎配置

text

◆  Search provider
│  ● Brave Search (Structured results · country/language/time filters)
│  ○ Gemini (Google Search)
│  ○ Grok (xAI)
│  ○ Kimi (Moonshot)
│  ○ Perplexity Search
│  ○ Skip for now

操作：

  • 想配置联网搜索 → 选 Brave Search（免费 2000 次/月）
  • 暂时不需要 → 选 Skip for now

如果选择 Brave Search，会提示输入 API Key：

3.7 技能配置

text

◆  Configure skills now? (recommended)
│  ● Yes / ○ No

操作： 保持选中 Yes，按回车

3.8 技能选择

text

◆  Install missing skill dependencies
│  ◻ Skip for now
│  ◻ 🔐 1password
│  ◼ 📝 apple-notes (Manage Apple Notes on macOS)
│  ◻ 🐻 bear-notes
│  ◻ 📰 blogwatcher
│  ◼ 🐙 github (GitHub operations via gh CLI)
│  ...更多选项...

操作：

  • 上下键：移动光标
  • 空格键：选中/取消技能
  • 回车键：确认安装

推荐选择：

  • apple-notes（Mac 备忘录管理）
  • github（GitHub 操作）

按回车确认

3.9 消息渠道配置

text

◆  Configure messaging channels now?
│  ● Yes / ○ No

操作：

  • 现在配置 → 选 Yes
  • 稍后配置 → 选 No

如果选 Yes，会依次询问各渠道（Telegram、飞书、钉钉等），选择 Skip 跳过即可。

3.10 网关配置

text

◆  Configure gateway settings?
│  ● Yes / ○ No

操作： 保持 Yes，按回车

text

◆  Gateway port (default: 18789)
│  [18789]

操作： 直接按回车（使用默认端口）

text

◆  Enable gateway authentication token?
│  ● Yes / ○ No

操作： 保持 Yes，按回车

系统会自动生成访问令牌，请保存好这个令牌（显示在终端中）。

3.11 完成配置

text

✓ Configuration complete!

🌐 第四部分：启动 OpenClaw

4.1 启动网关服务

bash

openclaw gateway start

成功启动会显示：

text

✓ Gateway started on http://127.0.0.1:18789
✓ Token: xxxxxxxxxxxxxxxxxxxx

4.2 访问 Web 控制台

打开浏览器访问：

text

http://127.0.0.1:18789

首次访问需要输入令牌：

  • 粘贴刚才生成的 token
  • 点击登录

📝 第五部分：常用命令速查
操作 命令
启动网关 openclaw gateway start
停止网关 openclaw gateway stop
查看状态 openclaw status
查看日志 openclaw logs
重启服务 openclaw gateway restart
添加渠道 openclaw channels add <channel>
安装技能 openclaw skills install <skill>
重新配置 openclaw onboard
生成新令牌 openclaw token generate

🆘 第六部分：常见问题

Q1: openclaw: command not found

bash

# 重新安装
npm install -g openclaw

# 或检查 npm 全局路径
npm root -g
# 确保该路径在 PATH 中

Q2: 网关启动失败（端口占用）

bash

# 查看占用进程
lsof -i :18789

# 杀掉进程
kill -9 <PID>

# 或换端口启动
openclaw gateway start --port 18888

Q3: 忘记访问令牌

bash

# 生成新令牌
openclaw token generate

# 查看现有令牌
openclaw token list

Q4: 如何添加 AI 模型

bash

# 重新运行配置
openclaw onboard

# 或直接编辑配置
open ~/.openclaw/config.json

✅ 安装完成检查清单

  • Homebrew 安装成功
  • Node.js v22+ 安装成功
  • OpenClaw 安装成功（openclaw --version）
  • openclaw onboard 完成配置
  • openclaw gateway start 成功启动
  • 浏览器能访问 http://127.0.0.1:18789
  • 能成功登录控制台