# 00. OpenClaw 文档阅读指南

> **课程信息**
>
> - **作者**：老金
> - **GitHub**：https://github.com/KimYx0207
> - **公众号**：老金带你玩AI
> - **X（Twitter）**：老金带你玩AI
> - **个人博客**：https://aiking.dev
> - **难度等级**：🟢 入门
> - **阅读时间**：10 分钟
> - **前置知识**：无

## 这份文档是写给谁的？

老金我把 OpenClaw 阅读路线拆得这么细，是为了让非程序员也能知道先跑通哪一步、卡住时查哪一层。

不管你是刚接触 AI 的小白，还是想深入定制的老手，这套教程都能帮到你。本系列共 **12 篇**（本篇 **00 阅读指南** + **01～11 正文**），不必逐篇通读。这篇指南帮你找到最适合自己的阅读路径。

---

## 术语表（先看这个）

在开始之前，先搞懂几个核心概念。后面所有文档都会用到这些词：

| 术语 | 一句话解释 | 类比 |
|------|-----------|------|
| **OpenClaw** | 一个开源的 AI 私人助手框架，跑在你自己的电脑上 | 相当于你雇了一个 AI 员工 |
| **Gateway** | OpenClaw 的核心服务进程，负责接收消息、调度 AI、返回回复 | 相当于公司的前台总机 |
| **Agent** | 一个独立的 AI 助手实例，有自己的性格、记忆和技能 | 相当于公司里的一个员工 |
| **Channel** | 消息平台的连接通道（WhatsApp、Telegram、Discord 等） | 相当于员工的工位电话 |
| **Skill（技能）** | 教 AI 如何完成特定任务的 Markdown 指令文件 | 相当于员工的操作手册 |
| **Tool（工具）** | AI 可以调用的单个功能（读文件、发消息、搜索等） | 相当于员工手边的工具 |
| **Session（会话）** | 你和 AI 的一次对话，包含上下文和历史 | 相当于一次面对面交谈 |
| **Memory（记忆）** | AI 跨会话记住的信息，存储在本地 Markdown 文件中 | 相当于员工的笔记本 |
| **DM Pairing（配对）** | 安全机制，新用户首次私聊 AI 时需要你手动批准 | 相当于访客登记制度 |
| **Sandbox（沙箱）** | 隔离环境，限制 AI 执行危险操作 | 相当于实验室的安全柜 |
| **JSON5** | OpenClaw 配置文件的格式，比 JSON 多了注释和尾逗号支持 | 相当于更人性化的 JSON |
| **onboard** | OpenClaw 的初始化引导向导 | 相当于新员工入职培训 |

---

## 文档地图

### 难度分级说明

- 🟢 **入门** — 零基础也能看懂，跟着做就行
- 🟡 **进阶** — 需要一点技术基础（会用命令行、了解 API 概念）
- 🔴 **高级** — 面向有经验的开发者和运维人员

### 全部文档一览

| 序号 | 文档 | 难度 | 一句话说明 | 什么人需要看 |
|------|------|------|-----------|-------------|
| 01 | [项目介绍](01-OpenClaw项目介绍.md) | 🟢 入门 | OpenClaw 是什么、能干什么、跟别的有什么不同 | 所有人 |
| 02 | [安装部署](02-安装部署指南.md) | 🟢 入门 | 怎么把 OpenClaw 装到你的电脑上 | 所有人 |
| 03 | [快速开始](03-快速开始指南.md) | 🟢 入门 | 5 分钟跑起第一个对话 | 所有人 |
| 04 | [模型配置](04-模型配置指南.md) | 🟡 进阶 | 怎么切换 AI 模型、配置 API Key | 想换模型的人 |
| 05 | [消息平台](05-消息平台接入指南.md) | 🟡 进阶 | 怎么把 AI 接到 WhatsApp、Telegram 等平台 | 想在手机上用的人 |
| 06 | [技能系统](06-技能系统指南.md) | 🟡 进阶 | 怎么教 AI 新技能、管理已有技能 | 想定制 AI 能力的人 |
| 07 | [记忆系统](07-记忆系统指南.md) | 🟡 进阶 | 怎么让 AI 记住你的偏好和历史 | 想让 AI 更懂你的人 |
| 08 | [多Agent协作](08-多Agent协作指南.md) | 🔴 高级 | 怎么创建多个 AI 助手分工协作 | 重度用户、团队使用 |
| 09 | [Docker部署](09-Docker部署指南.md) | 🔴 高级 | 怎么用 Docker 部署到服务器 | 运维人员、服务器部署 |
| 10 | [安全配置](10-安全配置指南.md) | 🔴 高级 | 怎么保护你的 AI 助手不被滥用 | 公网暴露、团队使用 |
| 11 | [常见问题](11-常见问题FAQ.md) | 🟢 入门 | 遇到问题来这里找答案 | 遇到问题的人 |

---

## 阅读路线图

### 先判断你要解决什么问题

OpenClaw 不是单纯的聊天网页，也不是只会跑命令的 CLI。它更像一个可以长期运行的 AI 网关：上面接消息平台，下面接模型和工具，中间有 Agent、技能、记忆、权限和 Gateway。学习时不要一上来追所有功能，先判断自己今天要解决哪个问题。

```text
如果你只是想和 AI 对话：
先看 01、02、03。

如果你想把 AI 接到手机或团队聊天：
先看 02、03、05，再回头看 10 的安全部分。

如果你想让 AI 长期记住你：
先看 03、07，再看 06 的技能组合。

如果你想做一个可长期运行的服务器：
先看 02、09、10，再看 05。

如果你想做多助手分工：
先看 06、07、08，不要第一天就上生产。
```

这套教程的读法和普通软件文档不同。普通文档按功能排列，课程读法应该按任务排列：安装、跑通、接平台、加技能、加记忆、上生产、做安全。

### 🚀 路线一：小白速通（30 分钟上手）

只想最快跑起来？按这个顺序，跳过所有标注"可跳过"的章节：

```
01-项目介绍（只看前 3 节，了解 OpenClaw 是什么）
    ↓
02-安装部署（跟着"快速安装"章节操作）
    ↓
03-快速开始（完整跟着做，5 分钟跑起第一个对话）
    ↓
搞定！你已经有一个能聊天的 AI 助手了 🎉
```

之后遇到问题去看 11-常见问题FAQ。

速通路线结束后，不要马上接 WhatsApp、Telegram、Slack。先用 Control UI 或 CLI 跑通一个最小对话，确认 Gateway、模型和配置都正常。否则平台接入失败时，你会分不清是模型问题、Gateway 问题，还是平台 Webhook 问题。

### 🔧 路线二：日常使用（2-3 小时）


想在手机上用、想让 AI 更聪明？在路线一的基础上加：

```

日常使用路线建议每次只增加一个变量。比如今天只接 Telegram，明天再开记忆，后天再加技能。OpenClaw 是长驻型工具，配置变化越多，排障越难。
路线一完成后
    ↓
04-模型配置（选择最适合你的 AI 模型）
    ↓
05-消息平台（把 AI 接到你的 WhatsApp/Telegram）
    ↓
06-技能系统（只看"内置技能"和"技能管理"章节）
    ↓
07-记忆系统（只看"基础配置"章节）
```

深度定制路线里最容易踩的坑，是把技能、工具、记忆、多 Agent 同时打开。更稳的顺序是：

```text
1. 先让一个 Agent 稳定完成任务。
2. 再把重复任务做成 Skill。
3. 再让 Memory 保存长期偏好。
4. 最后才拆出多个 Agent 分工。
```

### 🏗️ 路线三：深度定制（半天到一天）


想玩转所有功能？在路线二的基础上加：

```
路线二完成后
    ↓
06-技能系统（完整阅读，学会创建自定义技能）
    ↓
07-记忆系统（完整阅读，优化记忆策略）
    ↓
08-多Agent协作（创建专业分工的 AI 团队）
```

### 🔒 路线四：生产部署（需要运维经验）


要把 OpenClaw 部署到服务器给团队用？

```
路线二完成后
    ↓
09-Docker部署（容器化部署到服务器）
    ↓
10-安全配置（保护你的 AI 助手）
    ↓
08-多Agent协作（为不同团队成员配置不同 Agent）
```

生产路线里，安全配置不是最后的装饰，而是能否上线的前置条件。只要 Gateway 暴露到公网，至少要确认 token、TLS、反向代理头、DM Pairing、平台权限和日志策略。

---

## 第一周学习计划

如果你想把 OpenClaw 学成真正可用的工具，可以按下面 5 天推进。

### 第 1 天：跑通本地 Gateway

目标不是接所有平台，而是确认本机能运行。

```bash
openclaw onboard --install-daemon
openclaw gateway --port 18789 --verbose
openclaw doctor
```

你应该能回答：

```text
- 配置文件在哪里？
- Gateway 是否启动？
- 默认端口是多少？
- 当前模型提供商是谁？
- 失败时去哪看日志？
```

### 第 2 天：跑通第一个对话

用 Control UI 或 CLI 发送第一条消息。

```bash
openclaw agent --message "用一句话介绍你自己"
```

这一天只确认模型、Agent 和 Gateway 的基本链路。不要同时改模型、接平台、开多 Agent。

### 第 3 天：接一个低风险消息平台

优先选 Telegram 或 Web Chat 这类容易调试的平台。接入时只做三个动作：

```text
1. 配置 channel。
2. 发一条测试消息。
3. 看 Gateway 日志确认消息从平台进入 OpenClaw。
```

### 第 4 天：加一个技能或一条记忆

不要一次装很多技能。先选一个低风险技能，观察它如何改变回复。

```bash
openclaw skills list
```

然后让 AI 记住一个非敏感偏好：

```text
记住：我喜欢简洁的中文回答。
```

### 第 5 天：做一次安全检查

检查 Gateway token、配置文件权限、DM Pairing 和日志。

```bash
openclaw config get
openclaw doctor
```

这一天的目标是建立安全基线，而不是继续加功能。

---

## 三个典型学习场景

### 场景一：个人手机助手

推荐路线：

```text
01 -> 02 -> 03 -> 04 -> 05 -> 07
```

重点：

```text
- 模型稳定。
- 手机平台消息能收发。
- 记忆只保存非敏感偏好。
- DM Pairing 不要关闭。
```

不要急着做：

```text
- 多 Agent。
- Docker 生产部署。
- 自定义工具写入本机文件。
```

### 场景二：团队内部机器人

推荐路线：

```text
01 -> 02 -> 03 -> 05 -> 10 -> 06 -> 08
```

重点：

```text
- 先明确谁能和机器人对话。
- 团队频道和私聊策略分开。
- 技能要有 owner。
- 多 Agent 要有路由和权限边界。
```

不要急着做：

```text
- 让机器人自动执行生产操作。
- 把所有团队知识塞进记忆。
- 让多个 Agent 共用同一套高权限工具。
```

### 场景三：服务器长期运行

推荐路线：

```text
02 -> 09 -> 10 -> 05 -> 11
```

重点：

```text
- Docker volume 和配置备份。
- HTTPS / 反向代理。
- Gateway token。
- 日志和监控。
- 版本升级和回滚。
```

不要急着做：

```text
- Watchtower 自动更新后不看日志。
- 暴露 18789 到公网但不设认证。
- 把配置目录放在不备份的位置。
```

---

## 遇到问题时怎么读文档

不要直接在 FAQ 里搜索一个报错词就结束。更稳的排查路线是：

```text
安装失败：
先看 02，再看 11 的安装类问题。

能启动但不回复：
先看 03 的 Gateway / Control UI，再看 04 的模型配置。

平台收不到消息：
先看 05 的 channel 生命周期，再看 11 的消息平台问题。

AI 不按预期工作：
先看 06 的技能，再看 07 的记忆。

公网部署不放心：
先看 10，再回 09 检查 Docker 和反向代理。
```

每次排障都记录四件事：

```text
1. 当前命令。
2. 当前配置文件路径。
3. Gateway 日志关键行。
4. 你已经排除了什么。
```

这样你在 GitHub Issue、Discord 或团队群里提问时，别人能快速判断问题在哪一层。

---

## 按任务查文档：你现在想做什么

如果你已经有明确目标，可以不按章节顺序读，直接从任务入口跳。

| 你想做什么 | 推荐入口 | 你会得到什么 |
|---|---|---|
| 先知道 OpenClaw 是什么 | 01 项目介绍 | Gateway、Channel、Agent、Skill、Memory 的整体心智模型 |
| 在电脑上装起来 | 02 安装部署 | Node、CLI、onboard、Gateway、健康检查 |
| 五分钟内聊第一句 | 03 快速开始 | 第一条对话、Control UI、CLI 消息、日志定位 |
| 配一个可用模型 | 04 模型配置 | API Key、本地模型、fallback、成本控制 |
| 接 Telegram / Discord / Slack | 05 消息平台 | 平台凭据、Webhook/Polling、Pairing、频道日志 |
| 让 OpenClaw 会做固定工作 | 06 技能系统 | Skill 编写、触发、调试、权限边界 |
| 让 AI 记住你和项目 | 07 记忆系统 | USER/MEMORY/每日记忆、索引、迁移、遗忘 |
| 多个助手分工 | 08 多 Agent | Agent 工作空间、路由、Sessions 转交、共享目录 |
| 放到服务器长期跑 | 09 Docker 部署 | Compose、反代、volume、备份、更新回滚 |
| 防止误操作和泄露 | 10 安全配置 | Gateway、DM Pairing、沙箱、提示词注入、事故响应 |
| 问题卡住了 | 11 FAQ | 按问题类型快速定位 |

这张表建议你收藏。OpenClaw 涉及模型、消息平台、插件、文件系统和安全边界，很多问题看起来像同一个错误，实际源头可能完全不同。按任务入口读，可以减少无效排查。

## 一个下午的完整学习节奏

如果你有 3-4 小时，可以按下面节奏完成第一次系统学习。

### 第 0 阶段：先建立边界感

用 15 分钟读：

- 01 项目介绍的“一条消息的旅程”
- 10 安全配置的 Gateway 和 DM Pairing 部分

目的先知道 OpenClaw 不是普通聊天网页。它可以接消息平台、调用工具、写文件、加载记忆，所以安全边界从第一天就要考虑。

### 第 1 阶段：装起来并确认 Gateway

用 45 分钟读：

- 02 安装部署的系统要求、CLI 安装、onboard
- 03 快速开始的 Gateway 状态和 Control UI

只追求一件事：`openclaw health` 或 `openclaw doctor` 能给出可理解结果，Gateway 能在 `18789` 提供服务。不要在这一阶段接三个平台，也不要写复杂 Agent。

### 第 2 阶段：跑第一条稳定对话

用 30 分钟读：

- 03 快速开始的第一条消息
- 04 模型配置的 API Key 和模型状态

如果第一条消息失败，只排查模型。不要同时怀疑 Telegram、Docker、Skill、Memory。第一条稳定对话是整个课程的地基。

### 第 3 阶段：接一个低风险入口

用 45 分钟读：

- 05 消息平台的 Telegram 或 WebChat
- 10 安全配置的 DM Pairing

建议第一次选个人私聊或 WebChat，不要直接进团队大群。你要先知道消息到达、路由、回复、日志长什么样。

### 第 4 阶段：加一个小能力

用 45 分钟读：

- 06 技能系统的工坊
- 07 记忆系统的记忆整理练习

只做一个小能力：比如“整理反馈”或“记住写作偏好”。不要第一次就做多 Agent 自动协作。

### 第 5 阶段：写一页运行笔记

用 20 分钟写：

```markdown
# My OpenClaw Runbook

## 启动

- openclaw gateway --port 18789

## 检查

- openclaw health
- openclaw doctor
- openclaw channels status

## 当前模型

- provider:
- model:

## 当前入口

- WebChat:
- Telegram:

## 常见问题

- Gateway 没启动：
- 模型 Key 错误：
- 平台不回复：
```

这页笔记比你想象得重要。OpenClaw 的可用性来自一条链路：配置、Gateway、模型、入口、Agent、Skill、Memory。运行笔记会让你下次不用从头猜。

## 读者常见岔路

下面这些岔路很常见，提前知道会少走很多弯路。

### 岔路一：一开始就接最复杂的平台

Discord、Slack、飞书、WhatsApp 都有权限、事件订阅、Bot 审核或扫码状态。第一次学习建议先用 WebChat 或 Telegram 私聊。你先证明 Gateway 和模型没问题，再接复杂平台。

### 岔路二：模型没通就开始改 Agent

如果模型 provider 报错，改 SOUL.md 没有意义。先运行：

```bash
openclaw models status
openclaw models list
```

确认模型能返回，再讨论 Agent 的人格、技能和记忆。

### 岔路三：把所有偏好都塞进 MEMORY.md

记忆不是垃圾桶。长期稳定偏好写 `USER.md`，长期项目事实写 `MEMORY.md`，当天临时进展写 `memory/YYYY-MM-DD.md`。如果你把每次聊天都写进长期记忆，后面回答会越来越混乱。

### 岔路四：多 Agent 只是多写几个身份

多 Agent 的核心不是"多几个角色"，而是入口、工作空间、模型、工具、记忆、权限都能分开。没有路由和边界的多 Agent，只是多个名字不同的聊天助手。

### 岔路五：Docker 跑起来就算部署完成

Docker 只解决运行形态，不自动解决备份、反向代理、TLS、日志、升级回滚。长期运行至少要读 09 Docker 部署和 10 安全配置。

## 每章读完应该留下什么

读教程不是只留下“我看过了”。每章读完最好留下一个具体产物。

| 章节 | 读完后留下的产物 |
|---|---|
| 01 项目介绍 | 一张自己的 OpenClaw 架构草图 |
| 02 安装部署 | 一份安装记录和当前版本 |
| 03 快速开始 | 第一条成功对话和日志定位方法 |
| 04 模型配置 | 模型路由笔记和备用模型 |
| 05 消息平台 | 一个 Channel Runbook |
| 06 技能系统 | 一个本地 Skill |
| 07 记忆系统 | 整理后的 USER.md / MEMORY.md |
| 08 多 Agent | 一个明确路由的 Agent 分工 |
| 09 Docker 部署 | 一份 update/backup/restore 操作笔记 |
| 10 安全配置 | 一份最小安全加固配置 |
| 11 FAQ | 自己遇到问题的补充记录 |

这些产物都是读者自己的工作资产。课程的价值不在于看完多少页，而在于你能不能把 OpenClaw 变成一个稳定、可维护、可恢复的系统。

---

## 本系列的学习原则

### 先 Gateway，再平台

Gateway 是 OpenClaw 的核心。Control UI、消息平台、Agent、技能、记忆都依赖它。平台接入失败时，先确认 Gateway 是否正常。

### 先一个 Agent，再多 Agent

多 Agent 很吸引人，但第一天就拆多个 Agent 会让问题变复杂。先让默认 Agent 稳定工作，再拆专业分工。

### 先只读，再写入

任何会写文件、发消息、调用外部系统的能力，都先用只读或测试环境验证。

### 先手动，再自动

Watchtower、cron、自动备份、自动重启都很有用，但前提是你已经手动跑通过同样流程。

### 先安全，再公网

只要公网可访问，就必须先看安全配置。Gateway token、TLS、反向代理头、DM Pairing、日志都不是可有可无的细节。

---

## 贯穿全套课程的练习项目

如果你只读每章命令，很容易学完就忘。建议用一个小项目贯穿整套课程：做一个“个人到团队可迁移的 OpenClaw 助手”。

这个项目分四个阶段，不要求一天做完。

### 阶段一：本地个人助手

目标：

```text
在本机启动 Gateway，用 Control UI 或 CLI 完成稳定对话。
```

涉及章节：

- 01 项目介绍
- 02 安装部署
- 03 快速开始
- 04 模型配置

你会留下：

```text
- 当前安装方式。
- 当前 OpenClaw 版本。
- 默认模型。
- Gateway 启动命令。
- 第一条成功消息。
- 失败时看哪份日志。
```

这个阶段不要接公网，也不要做复杂多 Agent。你只需要证明“本机 -> Gateway -> 模型 -> 回复”这条线通了。

### 阶段二：手机入口助手

目标：

```text
把 OpenClaw 接到 Telegram 或其他低摩擦消息平台。
```

涉及章节：

- 05 消息平台接入
- 10 安全配置的 DM Pairing

你会留下：

```text
- 一个 Channel Runbook。
- Bot Token 存放位置。
- Pairing 策略。
- inbound / outbound 日志样例。
- 平台失效时的禁用方法。
```

这个阶段的重点不是"平台越多越好"，而是你能不能解释：消息从哪里来、谁能发、发给哪个 Agent、回复失败时查哪里。

### 阶段三：可复用工作能力

目标：

```text
让 OpenClaw 做一个固定工作，例如整理反馈、生成会议纪要、分类 issue。
```

涉及章节：

- 06 技能系统
- 07 记忆系统

你会留下：

```text
- 一个本地 Skill。
- 一个 examples/ 示例。
- 一份 USER.md 偏好。
- 一份 MEMORY.md 项目事实。
- 一条不写入敏感信息的规则。
```

这个阶段最容易犯的错，是把技能、记忆、模型混成一团。Skill 负责流程，Memory 负责长期上下文，模型负责生成和推理。它们不是同一件事。

### 阶段四：团队或服务器形态

目标：

```text
把 OpenClaw 变成能长期运行、能备份、能恢复、能加固的服务。
```

涉及章节：

- 08 多 Agent 协作
- 09 Docker 部署
- 10 安全配置
- 11 FAQ

你会留下：

```text
- 一个 Agent 分工草图。
- 一个 Docker Compose 或服务器运行手册。
- 一份备份恢复步骤。
- 一份安全事件处理笔记。
- 一份常见问题补充记录。
```

这个阶段才适合考虑多 Agent、Docker、反向代理、TLS、自动更新和长期日志。前面阶段没跑稳时，不要急着上服务器。

## 不同背景的人怎么读

### 完全新手

你可能不熟悉命令行、Node、API Key。先不要试图理解所有架构词。你的路线是：

```text
00 -> 01 -> 02 -> 03 -> 11
```

读的时候只做三件事：

```text
1. 跟着命令安装。
2. 跑通第一条消息。
3. 遇到错误记录原文。
```

暂时跳过：

```text
- 多 Agent。
- Docker。
- 自定义插件。
- 公网部署。
```

### 个人效率用户

你关心的是手机入口、记忆和固定工作流。你的路线是：

```text
00 -> 02 -> 03 -> 04 -> 05 -> 07 -> 06 -> 10
```

重点：

```text
- Telegram / WebChat 入口。
- USER.md 里的沟通偏好。
- MEMORY.md 里的长期事实。
- 一个小 Skill。
- Pairing 和 token 安全。
```

暂时不要把 OpenClaw 拉进很多群。先让它成为你的个人助手，再考虑团队协作。

### 开源项目维护者

你关心社区支持、FAQ、issue 分拣和文档反馈。你的路线是：

```text
00 -> 01 -> 03 -> 05 -> 06 -> 08 -> 10
```

重点：

```text
- Discord / Slack 测试频道。
- community 和 tech-support 的边界。
- issue-triage Skill。
- 公开频道不输出敏感信息。
- 技术问题转交和日志追踪。
```

不要让 AI 直接关闭 issue、发布公告或承诺修复时间。先让它整理、解释、引导和生成草稿。

### 团队管理员

你关心权限、部署、审计、成本和可维护性。你的路线是：

```text
00 -> 02 -> 04 -> 05 -> 08 -> 09 -> 10 -> 11
```

重点：

```text
- 默认模型成本。
- 哪些频道可以触发。
- 哪些 Agent 有工具权限。
- Docker volume 和备份。
- Gateway 不直接暴露公网。
- token 轮换和事故处理。
```

团队场景里，OpenClaw 一个带入口、权限和数据边界的小系统。

### 插件或技能开发者

你关心扩展面、工具、Skill、MCP、插件兼容。你的路线是：

```text
00 -> 01 -> 06 -> 07 -> 08 -> 10
```

重点：

```text
- Skill 的触发和边界。
- Tool 与 Skill 的区别。
- 插件白名单。
- 第三方能力的权限最小化。
- 测试 Agent 和真实 Agent 分开。
```

开发者最容易低估安全边界。只要你的技能会读写文件、调用外部 API 或处理用户消息，就必须读安全章节。

## 课程笔记建议

建议你在自己的工作空间建一个学习目录：

```bash
mkdir -p ~/openclaw-learning
cd ~/openclaw-learning
```

每章建一份笔记：

```text
00-reading.md
01-intro.md
02-install.md
03-quickstart.md
04-models.md
05-channels.md
06-skills.md
07-memory.md
08-agents.md
09-docker.md
10-security.md
11-faq.md
```

每份笔记只记录四类内容：

```md
# Chapter Note

## 我做了什么

...

## 当前配置

...

## 遇到的问题

...

## 下次继续

...
```

不要把教程全文复制一遍。笔记的价值是记录你自己的环境、选择和问题。

## 提问时怎么描述问题

无论你去 GitHub Issue、Discord、微信群，还是问 AI，描述问题时都尽量提供上下文。

模板：

```md
## 我想做什么

...

## 我运行的命令

```bash
...
```

## 当前环境

- OS:
- Node:
- OpenClaw:
- Install method:

## 现象

...

## 日志关键行

```text
...
```

## 我已经试过

...
```

一个好的问题描述能让别人直接判断问题在哪一层。只说“不能用”“不回复”“报错了”，通常会被迫来回追问。

## 30 天学习路线：从个人使用到可维护系统

如果你想系统学，而不是只临时查命令，可以按 30 天来安排。每天不需要很久，关键是每次只推进一个能力。

### 第 1 周：把最小链路跑稳

目标：

```text
本地 Gateway 能启动，默认 Agent 能回复，模型配置可解释，日志位置清楚。
```

安排：

| 天数 | 任务 | 对应章节 |
|---|---|---|
| Day 1 | 读项目介绍，画出 Gateway -> Agent -> Model 的链路 | 01 |
| Day 2 | 安装 CLI，运行 onboard，记录安装方式 | 02 |
| Day 3 | 用 Control UI 和 CLI 各发一条消息 | 03 |
| Day 4 | 配置默认模型，确认 API Key 或本地模型可用 | 04 |
| Day 5 | 看一次 Gateway 前台日志，标出消息进入和回复发出 | 03 |
| Day 6 | 写第一份 Quickstart Runbook | 03 |
| Day 7 | 回顾本周错误，把问题补到自己的笔记里 | 11 |

这一周不要接入正式群聊，也不要部署到服务器。你的任务是让最小链路稳定。

### 第 2 周：接入一个真实入口

目标：

```text
接入一个低风险消息平台，知道谁能发消息、消息进了哪个 Agent、失败时看哪份日志。
```

安排：

| 天数 | 任务 | 对应章节 |
|---|---|---|
| Day 8 | 选择一个入口：WebChat、Telegram 私聊或测试 Discord 频道 | 05 |
| Day 9 | 配置 token 或登录状态，保持 Pairing/allowlist | 05 / 10 |
| Day 10 | 发第一条平台消息，记录 inbound/outbound 日志 | 05 |
| Day 11 | 写 Channel Runbook | 05 |
| Day 12 | 测一次平台不回复时的排查路径 | 05 / 11 |
| Day 13 | 加一条隐私和敏感信息规则到 SOUL.md | 10 |
| Day 14 | 复盘入口是否适合长期使用 | 05 |

这一周的核心不是"能不能接更多平台"，而是能不能维护一个平台。

### 第 3 周：让助手有工作能力

目标：

```text
创建一个本地 Skill，整理一次记忆，让 OpenClaw 不只是聊天。
```

安排：

| 天数 | 任务 | 对应章节 |
|---|---|---|
| Day 15 | 选择一个重复工作，例如整理反馈或生成纪要 | 06 |
| Day 16 | 写最小 SKILL.md | 06 |
| Day 17 | 写一个 examples/ 示例 | 06 |
| Day 18 | 测触发词，观察日志 | 06 |
| Day 19 | 整理 USER.md 和 MEMORY.md | 07 |
| Day 20 | 重建记忆索引，测试召回 | 07 |
| Day 21 | 删除一条不该保存的记忆，演练遗忘流程 | 07 |

这一周要避免两个极端：一是只写很长提示词，不做 Skill；二是把所有聊天都塞进长期记忆。

### 第 4 周：走向团队和长期运行

目标：

```text
知道什么时候需要多 Agent，什么时候需要 Docker，如何处理安全和恢复。
```

安排：

| 天数 | 任务 | 对应章节 |
|---|---|---|
| Day 22 | 拆一个多 Agent 场景，但先不急着上线 | 08 |
| Day 23 | 设计频道到 Agent 的绑定 | 08 |
| Day 24 | 写一份 handover 文件，模拟 Agent 转交 | 08 |
| Day 25 | 阅读 Docker 部署，选择 volume 方案 | 09 |
| Day 26 | 写备份和恢复笔记 | 09 |
| Day 27 | 按安全工坊加固 Gateway、Pairing、SOUL.md | 10 |
| Day 28 | 演练 token 暴露后的处理流程 | 10 |
| Day 29 | 用 FAQ 回查自己遇到的问题 | 11 |
| Day 30 | 整理最终运行手册 | 00 |

30 天结束时，你应该拥有的不是"看过一套文档"的感觉，而是一套自己的 OpenClaw 运行资料：安装记录、模型路由、Channel Runbook、Skill、记忆文件、Agent 分工、部署和安全笔记。

## 每周复盘问题

每周结束时，问自己这些问题：

```text
1. 这一周新增了哪个能力？
2. 哪个配置变更最容易影响稳定性？
3. 哪条日志最有排查价值？
4. 有没有把敏感信息写入文档、日志或记忆？
5. 如果明天换一台机器，我能不能恢复？
6. 如果消息平台突然失效，我先看哪里？
7. 如果模型费用升高，我先查哪个入口？
```

这些问题会把你从“会用命令”带到“会维护系统”。OpenClaw 的学习难点不是单条命令，而是多层链路同时存在：入口、Gateway、模型、Agent、Skill、Memory、安全和部署。

## 课程里的命令怎么读

文档里有很多命令。读命令时建议区分三类：

```text
只读命令：
查看版本、状态、日志、配置。适合先运行。

配置命令：
修改模型、Channel、Agent、Skill。运行前记录原值。

高影响命令：
删除、重置、撤销 token、清理 volume、停服务。运行前确认备份和影响范围。
```

例子：

```bash
openclaw --version
openclaw channels status
openclaw models status
```

这些是只读命令，适合排查开头先跑。

```bash
openclaw config set agents.defaults.model openai/gpt-5.2-mini
```

这是配置命令，运行前最好先记录旧值：

```bash
openclaw config get agents.defaults.model
```

像下面这些就属于高影响动作：

```bash
docker compose down -v
openclaw reset
rm -rf ~/.openclaw
```

本教程会尽量把高影响动作写清楚，但你自己执行时也要先想：这会不会删除配置、记忆、凭证、volume 或会话历史？

## 按症状反查路线

OpenClaw 的问题常常表面相似。比如“Bot 不回复”可能是 Gateway 没启动、模型 Key 错、平台 token 失效、Pairing 没批准、路由给了错误 Agent，也可能只是平台限流。下面这张路线图适合排障时从症状反推。

### 症状一：命令行找不到 OpenClaw

先读：

```text
02 安装部署 -> Node/npm/PATH/权限
```

先运行：

```bash
node --version
npm --version
npm prefix -g
echo $PATH
```

不要先做：

```text
- 改 openclaw.json。
- 重新配置模型。
- 删除 ~/.openclaw。
```

这类问题通常还没进入 OpenClaw 配置层，而是在运行时和 shell 层。

### 症状二：Gateway 启动失败

先读：

```text
03 快速开始 -> Gateway 管理
02 安装部署 -> 端口和配置排查
```

先运行：

```bash
openclaw doctor
lsof -i :18789 || ss -tlnp | grep 18789
openclaw gateway --port 18789 --verbose
```

判断：

```text
端口占用：
先确认是不是旧 Gateway。

配置解析失败：
回到 openclaw.json 最近修改。

权限失败：
检查 ~/.openclaw 的 owner 和 chmod。
```

Gateway 是后面所有入口的基础。Gateway 没稳时，不要继续接 Telegram、Discord 或 Slack。

### 症状三：Control UI 能打开，但 AI 不回复

先读：

```text
04 模型配置
03 快速开始 -> 日志和模型链路
```

先运行：

```bash
openclaw models status
openclaw config get agents.defaults.model
openclaw agent --message "请只回复 ok"
```

常见原因：

```text
- API Key 未加载。
- 模型 ID 写错。
- provider 限流。
- 本地模型服务没启动。
- 上下文过长。
```

不要急着改 Agent。Agent 的表达方式会影响回答质量，但模型链路断了时，改 SOUL.md 没用。

### 症状四：Control UI 能聊，消息平台不回复

先读：

```text
05 消息平台接入
10 安全配置 -> Pairing 和 token
```

先运行通道状态和对应平台日志；完整命令清单放在 OC-03 快速开始和 OC-10 安全排障里，本阅读指南只提醒排查顺序。

排查顺序：

```text
1. 平台 token 是否有效。
2. Webhook / Polling 是否工作。
3. 私聊是否需要 Pairing。
4. 群聊是否需要 mention。
5. channelId / guildId 是否匹配。
6. 出站发送是否被平台限制。
```

这类问题说明 Gateway 和模型大概率是好的，坏在平台入口或出口。

### 症状五：AI 答得很怪，像忘了规则

先读：

```text
06 技能系统
07 记忆系统
08 多 Agent 协作
```

先看：

```bash
openclaw skills list
openclaw memory status
```

再检查：

```text
- 当前消息进了哪个 Agent。
- SOUL.md 是否具体。
- 是否触发了不相关 Skill。
- MEMORY.md 是否过期或冲突。
- 每日日志是否被误当成长期事实。
```

不要把这类问题都归因于“模型不行”。很多时候是上下文、技能或记忆给了模型错误信号。

### 症状六：Docker 更新后数据不见了

先读：

```text
09 Docker 部署 -> volume 和恢复
02 安装部署 -> 安装方式切换
```

先运行：

```bash
docker compose ps
docker volume ls
docker inspect openclaw-gateway | grep -A 20 Mounts
```

重点判断：

```text
- 有没有挂载 /home/node/.openclaw。
- 旧 volume 是否还在。
- compose 项目名是否变了。
- 是否运行过 docker compose down -v。
```

Docker 容器可以删，数据 volume 不能随便删。更新前备份，恢复前确认 volume 名称。

### 症状七：费用突然升高

先读：

```text
04 模型配置 -> 成本控制
05 消息平台 -> 群聊费用和滥用控制
```

先查：

```text
- 哪个入口触发最多。
- 哪个 Agent 使用强模型。
- 是否有自动任务循环。
- 是否有群聊所有消息都进模型。
- 是否有长上下文反复提交。
```

处理顺序：

```text
1. 暂停高频入口或改为 mention 触发。
2. 高频 Agent 切到低成本模型。
3. 限制长回答和自动摘要。
4. 再分析是否需要强模型。
```

不要一上来把所有模型都换成最便宜的。成本控制要看任务类型，不是只看单价。

## 读完后的个人运行档案

建议你最终整理一份 `OPENCLAW-RUNBOOK.md`。它不是公开教程，而是你自己的运行档案。

```md
# OpenClaw Runbook

## 1. Current Setup

- Install method:
- OpenClaw version:
- OS:
- Node:
- Config path:
- Workspace path:

## 2. Start / Stop

- Start:
- Stop:
- Health:
- Doctor:

## 3. Model

- Default model:
- Strong model:
- Local model:
- Fallback:

## 4. Channels

| Platform | Purpose | Agent | Owner | Disable |
|---|---|---|---|---|
| WebChat | test | main | me | stop Gateway |
| Telegram | personal | main | me | disable channel |

## 5. Agents

| Agent | Workspace | Model | Skills | Boundary |
|---|---|---|---|---|
| main | ~/.openclaw/workspace | ... | ... | ... |

## 6. Skills

- Installed:
- Local:
- Disabled:

## 7. Memory

- USER.md:
- MEMORY.md:
- Index command:
- Sensitive data rule:

## 8. Backup

- What:
- Where:
- Command:
- Last restore test:

## 9. Security

- Gateway token:
- Pairing:
- TLS / proxy:
- Sandbox:
- Log redaction:

## 10. Known Issues

- ...
```

这份档案会让你从“会照着教程操作”变成“知道自己系统是什么样”。OpenClaw 这种长期运行工具，最怕所有知识都留在聊天记录里。

## 最后一张速查卡

当你忘了下一步该看哪章时，用这张卡：

```text
装不上：
看 02。

能装但不会用：
看 03。

能聊但回答失败：
看 04。

平台不回复：
看 05。

想让它固定做一件事：
看 06。

想让它记住长期信息：
看 07。

想拆多个助手：
看 08。

想放服务器：
看 09。

担心安全和滥用：
看 10。

已经报错了：
看 11。
```

如果你只记住一句话：先把一条链路跑稳，再加下一层能力。OpenClaw 的学习顺序不是"功能越多越好"，而是每一层都知道怎么启动、怎么观察、怎么暂停、怎么恢复。

## 版本差异提醒

OpenClaw 更新很快，你本机命令的细节可能和文档略有差异。遇到这种情况，先看当前 CLI 的帮助，而不是硬套旧命令：

```bash
openclaw --help
openclaw channels --help
openclaw models --help
openclaw skills --help
```

如果帮助输出和教程不同，以当前安装版本为准，再把差异记录到自己的 Runbook。教程负责教你理解链路和排查方法，具体参数要跟随你正在运行的版本。

遇到命令不确定时，优先在本机看帮助，再回教程找上下文。这样既不会被旧参数卡住，也能把“这个命令属于哪一层”想清楚。

如果你把本机帮助输出和本教程的差异写进自己的运行档案，下一次升级、迁移或求助时会轻松很多。
记录差异时也写上日期和版本号，避免以后把旧环境经验误当成当前状态。

## 遇到问题怎么办？

1. 先看 [11-常见问题FAQ](11-常见问题FAQ.md)，80% 的问题都有现成答案
2. 运行 `openclaw doctor` 让系统自动诊断
3. 到 [GitHub Issues](https://github.com/openclaw/openclaw/issues) 搜索或提问
4. 加入 OpenClaw Discord 社区寻求帮助

---

## 文档约定

本套文档中使用以下标记：

| 标记 | 含义 |
|------|------|
| 🟢 **入门** | 零基础可读 |
| 🟡 **进阶** | 需要一点技术基础 |
| 🔴 **高级** | 面向有经验的开发者 |
| 💡 **提示** | 有用的小技巧 |
| ⚠️ **注意** | 容易踩的坑 |
| 🚫 **危险** | 操作不当可能造成数据丢失或安全问题 |
| 📖 **延伸阅读** | 想深入了解可以看这里 |
| ⏭️ **小白可跳过** | 新手不需要看这个章节 |