OpenClaw（原名 Clawdbot，昵称“小龙虾”）是一个**本地优先、强执行能力**的开源 AI 智能体（Agent）框架。它的核心价值在于让 AI **“真正能做事”**——通过自然语言指令自动拆解任务、调用工具（Skills），在设备上完成实际操作，如文件处理、浏览器自动化、多平台联动等，而非仅提供对话回答。

本教程将从零开始，手把手教你在不同平台（Windows、macOS、Linux）上部署 OpenClaw，配置免费的大模型 API，并安装实用的技能（Skills），最终搭建出属于你自己的个人 AI 智能体系统。

---

## 第一部分：部署前准备（全平台通用）

在开始安装之前，需要确保你的环境和账号满足以下要求。

### 1.1 硬件与系统要求
- **内存**：≥4GB（推荐 8GB 以上，多任务或复杂 Skills 需要更多）。
- **硬盘**：可用空间 ≥10GB。
- **系统**：
    - **Windows**: Windows 10/11 专业版或企业版（**强烈推荐使用 WSL2**，原生支持较差）。
    - **macOS**: macOS 12 及以上（兼容 Intel/Apple Silicon）。
    - **Linux**: Ubuntu 20.04+/Debian 11+/Fedora 38+。

### 1.2 核心依赖
- **Node.js**：版本必须 **≥ 22.0.0**（18/20 版本可能存在兼容性问题）。
- **Git**：用于克隆代码和版本管理。
- **Python**：版本 ≥ 3.9（部分 Skills 执行依赖）。

### 1.3 账号准备（以阿里云百炼为例）
为了获得大模型的理解和生成能力，你需要一个大模型 API。本教程以 **阿里云百炼** 为例，因为它为新用户提供 **90天免费额度**，且国内访问稳定。
1.  注册并登录阿里云账号，完成**实名认证**。
2.  访问阿里云百炼大模型服务平台，开通服务。
3.  进入“**密钥管理**”，点击“**创建API-Key**”，生成并**妥善保存**你的 `Access Key ID` 和 `Access Key Secret`（Secret 仅创建时可见）。

### 1.4 网络环境优化（国内用户必看）
由于 GitHub 和 npm 源在国外，直接安装可能很慢或失败，建议提前配置国内镜像加速。
```bash
# 配置 npm 国内淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry
```

---

## 第二部分：OpenClaw 核心安装与初始化

OpenClaw 提供了跨平台的一键安装脚本，可以自动处理大部分依赖，是新手的最佳选择。

### 2.1 一键安装 OpenClaw
根据你的操作系统，在终端（Linux/macOS）或 PowerShell（Windows）中执行相应命令。

- **macOS / Linux**:
  ```bash
  # 使用官方安装脚本（推荐）
  curl -fsSL https://openclaw.ai/install.sh | bash
  # 如果需要安装测试版，可以加上 -Tag beta 参数
  # curl -fsSL https://openclaw.ai/install.sh | bash -s -- -Tag beta
  ```
  *注：macOS 用户也可通过 Homebrew 安装 Node.js 22 后，再用此命令安装* 。

- **Windows 11 (强烈推荐 WSL2 方案)**:
  1.  以管理员身份打开 PowerShell，安装 WSL2 和 Ubuntu 子系统：
      ```powershell
      wsl --install -d Ubuntu
      ```
      重启电脑，完成 Ubuntu 的初始化设置（用户名和密码）。
  2.  打开 Ubuntu 终端，执行与 Linux 相同的安装命令：
      ```bash
      curl -fsSL https://openclaw.ai/install.sh | bash
      ```

- **Windows 11 (原生 PowerShell 备选方案)**:
  1.  以**管理员身份**打开 PowerShell。
  2.  解锁脚本执行权限（仅对当前进程有效）：
      ```powershell
      Set-ExecutionPolicy Bypass -Scope Process -Force
      ```
  3.  执行安装命令：
      ```powershell
      # 官方 beta 版脚本
      & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta
      
      # 或使用国内镜像脚本
      # iwr -useb https://clawd.org.cn/install.ps1 | iex
      ```

安装完成后，验证是否成功：
```bash
openclaw --version
# 预期输出：2026.x.x 版本号
```

### 2.2 初始化配置与启动网关
OpenClaw 的核心是一个叫 `Gateway` 的服务，它负责提供 Web 控制台和处理任务。

1.  **初始化配置**：
    ```bash
    openclaw init
    # 或者使用更详细的向导模式（推荐）
    openclaw onboard
    ```
    在 `onboard` 向导中，可以大部分情况选择默认选项（直接回车）。关键步骤提示：
    - **模型提供商**：可以先选“Custom Provider”，后续再配置。
    - **技能初始化**：选择“Yes”，启用核心技能框架。
    - **网关端口**：保持默认 `18789`。

2.  **配置网关模式**（本地部署必做）：
    ```bash
    openclaw config set gateway.mode local
    ```

3.  **启动网关服务**：
    ```bash
    openclaw gateway start
    # 验证状态
    openclaw gateway status
    # 预期输出：Gateway running on port 18789
    ```

4.  **生成访问令牌（Token）**：
    Token 是登录 Web 控制台的密码，非常重要。
    ```bash
    openclaw token generate
    # 查看生成的 token（复制并保存）
    cat ~/.openclaw/openclaw.json | grep '"token"'
    # Windows (PowerShell): type $env:USERPROFILE\.openclaw\openclaw.json | findstr "token"
    ```

### 2.3 验证部署
打开浏览器，访问 `http://localhost:18789/?token=你的Token`。如果能看到 OpenClaw 的对话界面，恭喜你，核心部署成功！

---

## 第三部分：配置大模型 API（以阿里云百炼为例）

OpenClaw 本身不包含大模型，需要对接外部 API 来获得智能。以下是配置阿里云百炼 API 的详细步骤。

### 3.1 通过命令行配置 API 密钥
将你在第一部分准备的阿里云百炼 API 密钥配置到 OpenClaw 中。
```bash
# 1. 配置百炼 API 密钥（替换为你的真实信息）
openclaw config set models.providers.bailian.accessKeyId "你的Access Key ID"
openclaw config set models.providers.bailian.accessKeySecret "你的Access Key Secret"

# 2. 配置国内接口地址（使用阿里云 DashScope 兼容地址）
openclaw config set models.providers.bailian.baseUrl "https://dashscope.aliyuncs.com/compatible-mode/v1"

# 3. 设置默认模型（例如通义千问3.5）
openclaw config set models.default "qwen3.5"

# 4. （可选）配置超时时间，避免网络波动影响
openclaw config set models.timeout 60000
```

### 3.2 其他模型提供商（备选）
除了阿里云百炼，OpenClaw 还支持众多其他模型：
- **七牛云**：在配置文件中设置 `baseUrl: "https://api.qnaigc.com/v1"` 和你的 `QINIU_API_KEY`，模型 ID 格式为 `qiniu/deepseek-v3.2-251201`。
- **本地模型**：也可以通过 Ollama 等工具集成本地运行的 Qwen2.5、Llama 3 等开源模型。

---

## 第四部分：扩展技能（Skills）

Skills 是 OpenClaw 的“手脚”，让它能真正执行任务。OpenClaw 预装了基础的 `agent-browser` 技能，使其具备网页访问能力。

### 4.1 安装新技能
你可以从 ClawHub 社区安装海量的技能。以下安装三个“拯救打工人”的神级 Skill 为例。

```bash
# 1. 安装日报生成技能 (daily-report)
# 它会指导 AI 读取任务记录、按模板生成日报并发送
openclaw skill install daily-report

# 2. 安装长文摘要技能 (summarize)
# 用于快速提炼长文章、网页、PDF 的核心内容
openclaw skill install summarize

# 3. 安装会议纪要整理技能 (meeting-minutes)
# 将语音转文字后的会议记录整理成结构化的纪要
openclaw skill install meeting-minutes
```

### 4.2 技能管理技巧
- **查看已安装技能**：`openclaw skill list`
- **技能存储位置**：你的所有定制化数据（包括 Skills、提示词、记忆）都应保存在 `~/.openclaw/workspace/` 目录下，这样可以安全更新 OpenClaw 版本而不会丢失个人配置。
- **技能选择原则**：“痛点优先、安全第一、轻量化”。不要盲目安装过多技能，以免造成资源浪费或冲突。

---

## 第五部分：进阶配置与常见问题

### 5.1 配置开机自启（守护进程）
为了让 OpenClaw 在后台 7x24 小时运行，需要将其安装为系统服务。

- **macOS**（使用 launchd）：
  ```bash
  openclaw service install mac
  launchctl load ~/Library/LaunchAgents/com.openclaw.gateway.plist
  ```

- **Linux**（使用 systemd）：
  ```bash
  # 安装服务（可能需要 sudo）
  sudo openclaw gateway install
  # 或者手动创建 systemd 服务文件
  sudo systemctl enable openclaw
  sudo systemctl start openclaw
  # 对于用户级服务，为防止用户注销后服务停止，需启用 lingering
  sudo loginctl enable-linger $USER
  ```

- **Windows**（使用计划任务）：
  ```bash
  openclaw gateway install
  ```
  这会在任务计划程序中创建一个使用 `SYSTEM` 账户运行的任务，实现登录自动启动。

### 5.2 重要文件存储路径
了解这些路径有助于你进行备份和迁移。
- **配置文件**：`~/.openclaw/openclaw.json`
- **工作区（Skills， 提示词， 记忆）**：`~/.openclaw/workspace/`
- **凭证（各类账号登录信息）**：`~/.openclaw/credentials/`
- **会话记录**：`~/.openclaw/agents/<agentId>/sessions/`
- **日志文件**：`/tmp/openclaw/` (macOS/Linux) 或 `$env:APPDATA\openclaw\logs\` (Windows)

### 5.3 新手常见问题避坑指南

1.  **端口被占用**：
    - **现象**：启动 Gateway 时报错 `EADDRINUSE`。
    - **解决**：修改默认端口，`openclaw gateway start --port 3001`，并在防火墙放行新端口。

2.  **Windows 原生部署权限不足**：
    - **现象**：安装或启动失败，提示权限错误。
    - **解决**：务必以**管理员身份**运行 PowerShell，并将 OpenClaw 目录（如 `C:\Users\你的用户名\.openclaw`）添加到 **Windows Defender 排除列表**，避免被误判。

3.  **阿里云国内地域网络受限**：
    - **现象**：无法从海外 ClawHub 下载 Skills，或某些海外服务（如 WhatsApp）Skills 调用失败。
    - **解决**：在阿里云选购服务器时，**地域优先选择“中国香港”或“美国弗吉尼亚”**，这两个地域免备案且网络限制少。

4.  **Token 泄露风险**：
    - **现象**：他人未经授权访问你的 OpenClaw 控制台。
    - **解决**：定期使用 `openclaw token generate` 重新生成 Token，并妥善保管，不要明文存储在公开位置。

---

通过以上步骤，你已经从零搭建了一个属于自己的、功能强大的 AI 智能体系统。OpenClaw 的真正魅力在于其无限的扩展性，现在，你可以开始探索 ClawHub 上超过 1.3 万个 Skills，或者尝试编写自己的 Skill，让你的“数字员工”完成更多专属任务。