# OpenClaw 部署指南（Windows + Mac mini）
> 适用于全新电脑，中国大陆网络环境优化

---

## 系统要求

- **Windows**: Windows 10 (1709+) 或 Windows 11
- **Mac mini**: macOS 12+
- **Node.js**: 22.16+ (推荐 24.x)
- **Python**: 3.10+ (Skillhub 和部分 Skill 需要)
- **网络**: 需要能访问 npm registry（已配置国内镜像）

---

## 第一部分：手动安装（跟着做）

### 0. 安装 winget（如果系统没有）

> winget 是 Windows 自带的包管理器（Win10 1709+）。先检查：
> ```
> winget --version
> ```
> 如果能输出版本号，跳过这步。如果提示找不到命令，执行下面的命令安装：

```powershell
# 方法 A：命令行一键安装
Invoke-WebRequest "https://github.com/microsoft/winget-cli/releases/latest/download/Microsoft.DesktopAppInstaller_8wekyb3d8bbwe.msixbundle" -OutFile "$env:TEMP\winget.msixbundle"; Add-AppxPackage "$env:TEMP\winget.msixbundle"

# 方法 B：如果上面的命令报错，打开 Microsoft Store，搜索「应用安装程序」并更新
```

### 1. 安装 Node.js

**Windows：**

```powershell
# 方法 A：winget（推荐，Win10 1709+ 自带）
winget install OpenJS.NodeJS.LTS

# 方法 B：Chocolatey（如果已安装）
choco install nodejs-lts

# 方法 C：PowerShell 一键静默安装（winget 不可用时）
Invoke-WebRequest "https://nodejs.org/dist/v22.16.0/node-v22.16.0-x64.msi" -OutFile "$env:TEMP\node-setup.msi"; msiexec /i "$env:TEMP\node-setup.msi" /quiet /norestart

# 方法 D：国内加速版（网络不好时用这个）
Invoke-WebRequest "https://registry.npmmirror.com/-/binary/node/v22.16.0/node-v22.16.0-x64.msi" -OutFile "$env:TEMP\node-setup.msi"; msiexec /i "$env:TEMP\node-setup.msi" /quiet /norestart
```

> **注意**：方法 C 和 D 是静默安装，粘贴执行即可自动完成，无需手动操作。安装完成后需要**重新打开终端**才生效。

**Mac：**
```bash
brew install node
```

**版本管理器（进阶，适合需要多版本切换的用户）：**
```bash
# fnm（推荐，跨平台，速度快）
winget install Schniz.fnm   # Windows
brew install fnm             # Mac
fnm install 24
fnm use 24
```

验证：打开新终端，输入 `node -v`，应显示 22.16+ 或 24.x

### 2. 安装 Git

**Windows：**
```powershell
# 方法 A：winget（推荐，Win10 1709+ 自带）
winget install Git.Git

# 方法 B：PowerShell 一键安装（winget 不可用时）
Invoke-WebRequest "https://registry.npmmirror.com/-/binary/git-for-windows/v2.53.0.windows.1/Git-2.53.0-64-bit.exe" -OutFile "$env:TEMP\Git-Setup.exe"; Start-Process "$env:TEMP\Git-Setup.exe"

# 方法 C：手动下载
# 浏览器打开 https://registry.npmmirror.com/-/binary/git-for-windows/
# 下载最新的 64-bit.exe 安装包，双击安装
```

**Mac：**
```bash
brew install git
```

验证：`git --version`（应显示 2.53.0 或更高）

> 如果提示"缺少 VCRUNTIME140.dll"，安装 Windows VC++ 运行库：https://aka.ms/vs/17/release/vc_redist.x64.exe

### 3. 安装 OpenClaw

**3.1 配置 npm 镜像**
```powershell
npm config set registry https://registry.npmmirror.com
```

**3.2 安装 OpenClaw**
```powershell
npm install -g openclaw@latest
```

### 4. 运行引导配置

```powershell
openclaw onboard --install-daemon
```

引导中选择模型时，填写：
- 提供商：Anthropic 兼容模式
- API Key：c66cfb82f6254b1f911c9e839ea6de36.NEXzUmLSlqiOeKmS
- Base URL：`https://open.bigmodel.cn/api/anthropic`
- 模型：GLM-5-Turbo

### 5. 创建桌面启动快捷方式

安装完成后，下载启动脚本放到桌面，以后双击即可启动 OpenClaw。

**Windows（BAT 版本）：**

下载启动脚本到桌面：`https://www.wubug.cc/downloads/OpenClaw启动脚本.bat`

> 如果想开机自启动，把 bat 文件放到 `shell:startup`（Win+R 输入 `shell:startup` 回车）。

**Mac/Linux（Shell 版本）：**

在桌面新建 `启动OpenClaw.sh`，内容如下：
```bash
#!/bin/bash
echo "OpenClaw Gateway 启动中..."
openclaw gateway start
openclaw gateway status
echo "Web UI: http://127.0.0.1:18789/"
echo "按 Ctrl+C 停止"
wait
```

赋予执行权限：`chmod +x ~/Desktop/启动OpenClaw.sh`

> Mac 开机自启动：系统偏好设置 → 用户与群组 → 登录项 → 添加该脚本

### 7. 打开 Web UI

```powershell
openclaw dashboard
```

浏览器自动打开 http://127.0.0.1:18789/

---

## 第二部分：发给 OpenClaw 自动配置

> 安装完第一步后，把下面的内容完整复制，粘贴到 OpenClaw 的对话中（Web UI / Telegram / QQ 均可），OpenClaw 会自动完成所有配置。

---

请帮我完成以下配置：

### 1. 安装 Python 和 Skillhub

**Python（Skillhub 依赖）：**
```powershell
# Windows
winget install Python.Python.3.12

# Mac
brew install python@3.12
```
验证：`python3 --version`

**Skillhub（Skill 管理器）：**
```powershell
# Windows（需先装 Git）
irm https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

# Mac
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
```
验证：`skillhub --version`

### 2. 安装浏览器（Chrome）

OpenClaw 的 `browser` 工具需要 Google Chrome。先检查本地是否已有：

**Windows：**
```powershell
where.exe chrome
```
如果输出了路径，说明已安装，跳过这步。如果没有输出，执行：
```powershell
winget install Google.Chrome
```

**Mac：**
```bash
ls "/Applications/Google Chrome.app"
```
如果存在，跳过。否则：
```bash
brew install --cask google-chrome
```

### 3. 部署工作区模板

从服务器下载工作区模板并部署到本地 OpenClaw 工作区。

工作区模板包含：AI 行为规则（AGENTS.md）、人格定义（SOUL.md）、记忆系统（MEMORY.md）、浏览器控制规则（BROWSER_CONFIG.md）等配置文件。

操作步骤：
1. 下载文件：`https://www.wubug.cc/downloads/openclaw-workspace-template.zip`
2. 解压到 OpenClaw 工作区：
   - Windows: `C:\Users\你的用户名\.openclaw\workspace\`
   - Mac/Linux: `~/.openclaw/workspace/`
3. 重启 OpenClaw Gateway

### 4. 安装常用技能

通过 Skillhub 安装技能，完整列表见 `SKILLS_CONFIG.md`（含 8 大类 50+ 个 skill）。

**新手推荐（5 个）：**
```bash
skillhub install tavily-search find-skills self-improving-agent brainstorming memory
```

**日常使用推荐（14 个）：**
```bash
skillhub install tavily-search find-skills self-improving-agent brainstorming writing-plans memory session-logs blog-writer github weather nano-pdf video-frames ffmpeg-video-editor 1password
```

**AutoGLM 浏览器自动化（需要 AutoGLM 客户端）：**
```bash
skillhub install autoglm-browser-agent autoglm-websearch autoglm-deepresearch autoglm-open-link autoglm-generate-image autoglm-search-image
```

### 5. 测试浏览器控制能力

安装完技能后，请执行以下测试，验证浏览器是否正常工作。

**重要规则：**
- 读取页面内容必须用 `browser action=snapshot`，获取结构化数据（元素 + 文本 + ref）
- 禁止用截图来分析页面内容
- 截图只用于展示给用户看视觉效果

**测试步骤：**

1. 启动浏览器并打开百度：
```
browser action=start
browser action=navigate url="https://www.baidu.com"
```

2. 读取页面内容（用 snapshot，不要截图）：
```
browser action=snapshot refs=role
```
验证：应能看到搜索框、按钮等元素和对应的 ref 编号

3. 在搜索框输入文字并搜索：
```
browser action=act kind=fill ref=<搜索框的ref> text="OpenClaw AI"
browser action=act kind=click ref=<搜索按钮的ref>
```

4. 等待结果加载后，读取搜索结果（用 snapshot）：
```
Start-Sleep -Seconds 2
browser action=snapshot refs=role
```
验证：应能看到搜索结果列表，能提取标题、链接、摘要

5. 点击一个搜索结果：
```
browser action=act kind=click ref=<某个搜索结果的ref>
```

6. 读取新页面内容（用 snapshot）：
```
Start-Sleep -Seconds 2
browser action=snapshot refs=role
```

7. 关闭浏览器：
```
browser action=stop
```

**测试通过标准：**
- 能启动浏览器并打开百度
- snapshot 能获取到页面元素和 ref
- 能在搜索框输入文字并搜索
- 能读取搜索结果
- 能点击链接跳转到新页面
- 全程没有用截图来分析内容

**如果内置 browser 工具报 handshake timeout：**
切换到 HTTP API 方式（18791 端口），详见工作区模板中的 `OpenClaw浏览器控制教程.txt`

### 6. 在桌面创建启动文件

**Windows：**

下载启动脚本到桌面：`https://www.wubug.cc/downloads/OpenClaw启动脚本.bat`

**Mac/Linux：**

在用户桌面创建 `启动OpenClaw.sh` 文件，内容：
```bash
#!/bin/bash
echo "OpenClaw Gateway 启动中..."
openclaw gateway start
openclaw gateway status
echo "Web UI: http://127.0.0.1:18789/"
echo "按 Ctrl+C 停止"
wait
```

然后赋予执行权限：`chmod +x ~/Desktop/启动OpenClaw.sh`

### 7. 记住关键配置

**公司 API Key（智谱 GLM）：**
- API Key: c66cfb82f6254b1f911c9e839ea6de36.NEXzUmLSlqiOeKmS
- Base URL: `https://open.bigmodel.cn/api/anthropic`
- 可用模型: GLM-5-Turbo, GLM-5, GLM-4.7, GLM-4.5-Air

**下载页面文件管理 API：**
- 获取文件列表：`GET https://www.wubug.cc/api/downloads/editable`
- 读取文件：`GET https://www.wubug.cc/api/downloads/file/{文件名}`
- 更新文件：`PUT https://www.wubug.cc/api/downloads/file/{文件名}` Body: `{"content": "内容"}`
- 支持格式：.txt .md .json .yml .html

**工作区模板 zip 下载地址：** https://www.wubug.cc/downloads/openclaw-workspace-template.zip

### 8. 填写个人信息

编辑 `~/.openclaw/workspace/USER.md`，填入你的名字、时区、偏好等信息，AI 会记住这些信息。

### 9. 重启 Gateway

完成以上配置后，重启 OpenClaw Gateway 使配置生效：
```powershell
openclaw gateway restart
```

---

## 常用命令

| 命令 | 说明 |
|------|------|
| `openclaw dashboard` | 打开 Web UI |
| `openclaw gateway status` | 查看运行状态 |
| `openclaw gateway restart` | 重启服务 |
| `openclaw update` | 更新 OpenClaw |
| `openclaw configure` | 重新配置 |
| `skillhub list` | 查看已安装 skill |
| `skillhub install <name>` | 安装 skill |
| `skillhub search <关键词>` | 搜索 skill |

---

## 常见问题

**npm install 报 ENOENT spawn git？**
Git 没装或不在 PATH 中。安装 Git 后重新打开终端。

**npm install 报 sharp 构建错误？**
Mac 执行：`SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest`

**AI 响应慢或超时？**
GLM-5-Turbo 是推理模型需要思考时间，耐心等待（默认超时 180 秒）。

**如何切换模型？**
Web UI 里输入 `/model`，或编辑 `~/.openclaw/openclaw.json`

**Skillhub python3 not found？**
Skillhub CLI 需要 Python 3，确保已安装且 `python3` 在 PATH 中。

**如何安装扩展技能？**
```bash
skillhub search <关键词>
skillhub install <技能名>
```
不要使用 ClawHub（`npx clawhub`），限流严重，用 Skillhub。

**浏览器报 handshake timeout？**
切换到 HTTP API 方式（18791 端口），详见 `OpenClaw浏览器控制教程.txt`

**浏览器用截图分析页面而不是 snapshot？**
这是错误行为。读取内容必须用 `browser action=snapshot refs=role`，截图只用于展示视觉效果。如果 AI 这样做，提醒它查看 AGENTS.md 的浏览器规则。

---

## 工作区文件结构

```
~/.openclaw/workspace/
├── AGENTS.md          <- AI 行为规则（自动维护）
├── SOUL.md            <- AI 人格风格
├── USER.md            <- 你的个人信息
├── IDENTITY.md        <- AI 身份（名字、emoji）
├── MEMORY.md          <- AI 长期记忆（自动维护）
├── HEARTBEAT.md       <- 定时任务
├── TOOLS.md           <- 工具配置备忘录
├── BROWSER_CONFIG.md  <- 浏览器配置和工具选择规则
└── memory/            <- 每日记忆（自动生成）
```

以上文件除 USER.md 和 IDENTITY.md 外，均由 AI 自动维护，无需手动修改。

---

## 快速命令速查（复制粘贴版）

### Windows（全选复制）
```powershell
# 1. 安装 Node.js（任选一种）
winget install OpenJS.NodeJS.LTS
# 或手动下载: https://nodejs.org/dist/v24.0.0/node-v24.0.0-x64.msi
# 国内加速: https://registry.npmmirror.com/-/binary/node/v24.0.0/node-v24.0.0-x64.msi

# 2. 安装 Git（如果没有）
winget install Git.Git

# 3. 配置镜像
npm config set registry https://registry.npmmirror.com

# 4. 安装 OpenClaw
npm install -g openclaw@latest

# 5. 引导配置
openclaw onboard --install-daemon

# 6. 安装 Python + Skillhub
winget install Python.Python.3.12
irm https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

# 7. 打开 Web UI
openclaw dashboard
```
> Python、Skillhub、Chrome 等由 OpenClaw 在第二部分自动检查和安装。
```

### Mac mini（全选复制）
```bash
# 1. 安装 Homebrew（如果没有）
/bin/bash -c "$(curl -fsSL https://mirrors.ustc.edu.cn/misc/brew-install.sh)"

# 2. 配置国内镜像
export HOMEBREW_API_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.ustc.edu.cn/homebrew-bottles"

# 3. 安装 Node.js
brew install node

# 4. 安装 Git
brew install git

# 5. 安装 Python
brew install python@3.12

# 6. 配置 npm 镜像
npm config set registry https://registry.npmmirror.com

# 7. 安装 OpenClaw
npm install -g openclaw@latest

# 8. 安装 Skillhub
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

# 9. 安装 Chrome
brew install --cask google-chrome

# 10. 引导配置
openclaw onboard --install-daemon

# 11. 打开 Web UI
openclaw dashboard
```

---

> 下载地址：https://www.wubug.cc/downloads/OpenClaw安装指南.txt
> 浏览器教程：https://www.wubug.cc/downloads/OpenClaw浏览器控制教程.txt
> API 文档：https://www.wubug.cc/downloads/README-API使用说明.txt
> 工作区模板：https://www.wubug.cc/downloads/openclaw-workspace-template.zip
> 最后更新：2026-03-28