OpenClaw 安装与使用全指南总结

**飞书 (Feishu)** | ⭐⭐⭐ | 创建企业自建应用，配置**事件订阅** (长连接)。***生产环境**: 务必使用 **Docker** 部署，并严格遵循 **安全加固** 章节，切勿直接将 Gateway 暴露在公网。***架构特点**：**本地优先（Local-first）**，数据存储在本地 Markdown 文件中，不依赖企业云端，保护隐私。| **Slack** | ⭐⭐

翱翔的苍鹰

1794人浏览 · 2026-03-03 19:32:18

翱翔的苍鹰 · 2026-03-03 19:32:18 发布

以下是关于 **OpenClaw**（前身为 Clawdbot/Moltbot）的安装与使用教程的详细总结。

---

# OpenClaw 安装与使用全指南总结

## 1. 什么是 OpenClaw？
OpenClaw 是一个免费开源的**自主 AI 代理（AI Agent）**，由 Peter Steinberger 开发。
* **核心定位**：像“数字员工”一样在本地机器上“始终在线”运行。
* **主要功能**：通过大语言模型（LLM）执行任务，管理邮件、控制浏览器、处理工作流。
* **交互方式**：以消息平台（Telegram, WhatsApp, Discord, 飞书等）为主要用户界面。
* **架构特点**：**本地优先（Local-first）**，数据存储在本地 Markdown 文件中，不依赖企业云端，保护隐私。
* **⚠️ 安全警告**：由于能访问敏感服务（邮件、日历等），配置不当有安全风险。**不建议不懂命令行的用户直接使用。**

---

## 2. 系统要求与预备知识
* **硬件**：最低 1GB RAM（推荐 4GB+），5GB 硬盘。
* **操作系统**：macOS, Linux (Ubuntu 20.04+), Windows (需通过 WSL2)。
* **核心依赖**：
* **Node.js**: 版本需 **22.12.0+** (至关重要)。
* **API Key**: 需准备至少一个 AI 提供商的 Key (Anthropic, OpenAI, DeepSeek, Gemini 等)。

---

## 3. 安装方式（七种方法）

### 🟢 方法一：一键脚本安装（最推荐新手）
官方自动检测并安装 Node.js 环境。
* **macOS / Linux**:
```bash
curl -fsSL https://openclaw.ai/install.sh | bash
```
* **Windows (PowerShell)**: 需先安装 WSL2，然后运行官方 PS 脚本。
* **初始化**: 安装完成后运行 `openclaw onboard --install-daemon` 注册后台服务。

### 🔵 方法二：npm/pnpm 手动安装
适合熟悉 Node.js 环境的开发者。
1. **安装 Node.js 22+** (推荐使用 `nvm` 管理版本，避免系统包冲突)。
2. **全局安装**: `npm install -g openclaw@latest`
3. **验证**: `openclaw --version`
4. **运行向导**: `openclaw onboard --install-daemon`

### 🔒 方法三：Docker 安装（最安全/服务器推荐）
隔离运行，降低安全风险。
1. 克隆仓库：`git clone https://github.com/openclaw/openclaw.git`
2. 进入目录运行脚本：`./docker-setup.sh`
* 该脚本会自动构建镜像、运行向导、创建配置目录 (`~/.openclaw`)。
3. **管理服务**: 使用 `docker compose up -d` 启动，`docker compose logs -f` 查看日志。
4. **权限修复**: 若遇权限错误，执行 `sudo chown -R 1000:1000 ~/.openclaw`。

### 其他安装方式简述
* **源码构建**: 适合开发者，使用 `pnpm install` 和 `pnpm build`。
* **云服务器**: DigitalOcean 有一键 Marketplace 部署；通用 VPS 推荐使用 Docker 方式。
* **Windows WSL2**: 官方不支持原生 Windows，必须在 WSL2 (Ubuntu) 中按 Linux 步骤安装。
* **macOS App**: 提供图形界面菜单栏应用，适合不想用命令行的 Mac 用户。

---

## 4. 核心配置流程 (Onboarding)

无论哪种安装方式，最终都会进入 `openclaw onboard` 向导：
1. **选择 AI 提供商**: Anthropic (推荐), OpenAI, DeepSeek, Gemini 等。
2. **输入凭证**: 粘贴 API Key 或进行 OAuth 认证。
3. **选择模型**: 推荐 `claude-sonnet-4-5` 或 `gpt-4o`。
4. **配置 Gateway**: 默认端口 `18789`，绑定方式建议选 `loopback` (仅本机访问，最安全)。
5. **连接消息频道**: 可跳过，后续配置。
6. **安装 Daemon**: 设置为开机自启的后台服务。

### 配置文件 (`~/.openclaw/openclaw.json`)
* **agent.model**: 指定使用的模型。
* **gateway.bind**: 设为 `loopback` 防止公网暴露。
* **exec.ask**: 设为 `on`，在执行危险命令前询问用户。
* **channels**: 配置各消息平台的 Token 和策略。

---

## 5. 消息频道配置详解

OpenClaw 支持多种消息平台，配置逻辑类似：**创建 Bot -> 获取 Token/AppID -> 填入配置 -> 配对账户**。

**飞书特别配置点**：
* **连接模式**: 推荐 `websocket` (长连接)，无需公网 IP。
* **权限**: 必须申请 `im:message` 相关权限。
* **多账号**: 支持在一个实例配置多个飞书应用账号。
* **流式输出**: 可配置打字机效果，但需注意 API 限流。

---

## 6. 技能系统 (Skills) 与扩展
* **内置技能**: Shell (执行命令), Browser (控浏览器), File (读写), Email, Calendar 等。
* **安装技能**: `openclaw skills install <技能名>`。
* **ClawHub**: 技能注册表，可自动搜索安装第三方技能。
* ⚠️ **安全警示**: 第三方技能可能存在恶意代码（如数据泄露），仅安装可信来源的技能。
* **自定义技能**: 支持用 TypeScript 编写自定义工具。

---

## 7. 安全加固 (至关重要)

由于 OpenClaw 权限极大，必须严格执行以下安全措施：
1. **禁止公网暴露**: Gateway 绑定地址必须为 `loopback` (127.0.0.1)。如需远程访问，使用 **Tailscale** 等内网穿透工具。
2. **执行前确认**: 配置 `exec.ask: "on"`，防止 AI 随意执行危险命令。
3. **配对策略**: 设置 `dmPolicy: "pairing"`，陌生用户需管理员审批才能对话。
4. **白名单机制**: 配置 `allowFrom` 限制允许对话的用户 ID。
5. **沙盒隔离**: 启用 `sandbox.mode: "non-main"`，限制 AI 的文件访问范围。
6. **权限控制**: 严格限制 `~/.openclaw/` 目录权限 (`chmod 700`)。

---

## 8. 常用命令速查

* **服务管理**:
* `openclaw gateway status` (查看状态)
* `openclaw gateway restart` (重启)
* `openclaw gateway logs --follow` (实时查看日志)
* `openclaw dashboard` (打开 Web 控制 UI)
* **配置与配对**:
* `openclaw config show` (查看配置)
* `openclaw pairing list` (查看待配对请求)
* `openclaw pairing approve <平台> <码>` (批准配对)
* **诊断**:
* `openclaw doctor` (健康检查)
* `openclaw update` (更新版本)

---

## 9. 常见问题排查 (FAQ)

1. **`command not found`**: 需将 npm 全局 bin 路径加入环境变量 `PATH`。
2. **Node.js 版本冲突**: 尤其是 Ubuntu/WSL 下，系统自带旧版 Node 会与安装器冲突。
* *解决*: 彻底卸载旧版 (`sudo apt purge nodejs libnode-dev`)，推荐使用 `nvm` 安装 Node 22。
3. **收不到消息 (飞书/Telegram)**:
* 检查是否完成了 **配对 (Pairing)** 步骤。
* 飞书需检查是否配置了 **事件订阅** (`im.message.receive_v1`)。
* 检查 `groupPolicy` 和 `requireMention` 设置。
4. **Docker 权限错误 (EACCES)**: 修改挂载目录所有者为 UID 1000 (`chown -R 1000:1000`)。
5. **端口占用**: 默认端口 18789 被占用时，可在配置文件中修改端口。

---

## 10. 总结与建议路径

* **新手入门**: macOS/Linux 用户使用 **一键脚本**，配置 **Telegram** 频道体验最快。
* **国内企业/个人**: 强烈推荐配置 **飞书 (Feishu)** 频道，利用长连接优势，无需公网 IP 且稳定。
* **生产环境**: 务必使用 **Docker** 部署，并严格遵循 **安全加固** 章节，切勿直接将 Gateway 暴露在公网。
* **核心理念**: OpenClaw 是强大的本地自动化助手，但“能力越大，责任越大”，配置时的安全性是第一优先级。