00. OpenClaw 文档阅读指南
课程信息
⠀
-
作者：老金
-
GitHub：https://github.com/KimYx0207
-
公众号：老金带你玩AI
-
X（Twitter）：老金带你玩AI
-
个人博客：https://aiking.dev
-
难度等级：🟢 入门
-
阅读时间：10 分钟
-
前置知识：无
⠀
这份文档是写给谁的？
⠀
我把 OpenClaw 阅读路线拆得这么细，是为了让非程序员也能知道先跑通哪一步、卡住时查哪一层。
⠀
不管你是刚接触 AI 的小白，还是想深入定制的老手，这套教程都能帮到你。本系列共 12 篇（本篇 00 阅读指南 + 01～11 正文），不必逐篇通读。这篇指南帮你找到最适合自己的阅读路径。
先选一个今天能用上的任务
⠀
第一次只走一条短路线。已经能打开 Control UI 并收到回复，就直接做简报练习；尚未安装时，先完成安装与认证。
⠀
今天的需要
从这里开始
这次带走什么
把零散待办整理清楚
03：今日待办简报
一份去掉重复和已完成事项的清单
换个会话仍沿用自己的格式
07：记忆系统
保存必要偏好，并检查新会话是否读到
从手机或消息平台继续用
先做 03，再选 05 中一个常用平台
跑通一个明确的消息入口
不知道为什么没回复
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
项目介绍
🟢 入门
OpenClaw 是什么、能干什么、跟别的有什么不同
所有人
02
安装部署
🟢 入门
怎么把 OpenClaw 装到你的电脑上
所有人
03
快速开始
🟢 入门
5 分钟跑起第一个对话
所有人
04
模型配置
🟡 进阶
怎么切换 AI 模型、配置 API Key
想换模型的人
05
消息平台
🟡 进阶
怎么把 AI 接到 WhatsApp、Telegram 等平台
想在手机上用的人
06
技能系统
🟡 进阶
怎么教 AI 新技能、管理已有技能
想定制 AI 能力的人
07
记忆系统
🟡 进阶
怎么让 AI 记住你的偏好和历史
想让 AI 更懂你的人
08
多Agent协作
🔴 高级
怎么创建多个 AI 助手分工协作
重度用户、团队使用
09
Docker部署
🔴 高级
怎么用 Docker 部署到服务器
运维人员、服务器部署
10
安全配置
🔴 高级
怎么保护你的 AI 助手不被滥用
公网暴露、团队使用
11
常见问题
🟢 入门
遇到问题来这里找答案
遇到问题的人
阅读路线图
⠀
先判断你要解决什么问题
⠀
OpenClaw 不是单纯的聊天网页，也不是只会跑命令的 CLI。它更像一个可以长期运行的 AI 网关：上面接消息平台，下面接模型和工具，中间有 Agent、技能、记忆、权限和 Gateway。学习时不要一上来追所有功能，先判断自己今天要解决哪个问题。
⠀
如果你只是想和 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 同时打开。更稳的顺序是：
⠀
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
⠀
目标不是接所有平台，而是确认本机能运行。
⠀
openclaw onboard --install-daemon
openclaw gateway --port 18789 --verbose
openclaw doctor
⠀
你应该能回答：
⠀
- 配置文件在哪里？
- Gateway 是否启动？
- 默认端口是多少？
- 当前模型提供商是谁？
- 失败时去哪看日志？
⠀
第 2 天：跑通第一个对话
⠀
用 Control UI 或 CLI 发送第一条消息。
⠀
openclaw agent --message "用一句话介绍你自己"
⠀
这一天只确认模型、Agent 和 Gateway 的基本链路。不要同时改模型、接平台、开多 Agent。
⠀
第 3 天：接一个低风险消息平台
⠀
优先选 Telegram 或 Web Chat 这类容易调试的平台。接入时只做三个动作：
⠀
1. 配置 channel。
2. 发一条测试消息。
3. 看 Gateway 日志确认消息从平台进入 OpenClaw。
⠀
第 4 天：加一个技能或一条记忆
⠀
不要一次装很多技能。先选一个低风险技能，观察它如何改变回复。
⠀
openclaw skills list
⠀
然后让 AI 记住一个非敏感偏好：
⠀
记住：我喜欢简洁的中文回答。
⠀
第 5 天：做一次安全检查
⠀
检查 Gateway token、配置文件权限、DM Pairing 和日志。
⠀
openclaw config get
openclaw doctor
⠀
这一天的目标是建立安全基线，而不是继续加功能。
三个典型学习场景
⠀
场景一：个人手机助手
⠀
推荐路线：
⠀
01 -> 02 -> 03 -> 04 -> 05 -> 07
⠀
重点：
⠀
- 模型稳定。
- 手机平台消息能收发。
- 记忆只保存非敏感偏好。
- DM Pairing 不要关闭。
⠀
不要急着做：
⠀
- 多 Agent。
- Docker 生产部署。
- 自定义工具写入本机文件。
⠀
场景二：团队内部机器人
⠀
推荐路线：
⠀
01 -> 02 -> 03 -> 05 -> 10 -> 06 -> 08
⠀
重点：
⠀
- 先明确谁能和机器人对话。
- 团队频道和私聊策略分开。
- 技能要有 owner。
- 多 Agent 要有路由和权限边界。
⠀
不要急着做：
⠀
- 让机器人自动执行生产操作。
- 把所有团队知识塞进记忆。
- 让多个 Agent 共用同一套高权限工具。
⠀
场景三：服务器长期运行
⠀
推荐路线：
⠀
02 -> 09 -> 10 -> 05 -> 11
⠀
重点：
⠀
- Docker volume 和配置备份。
- HTTPS / 反向代理。
- Gateway token。
- 日志和监控。
- 版本升级和回滚。
⠀
不要急着做：
⠀
- Watchtower 自动更新后不看日志。
- 暴露 18789 到公网但不设认证。
- 把配置目录放在不备份的位置。
遇到问题时怎么读文档
⠀
不要直接在 FAQ 里搜索一个报错词就结束。更稳的排查路线是：
⠀
安装失败：
先看 02，再看 11 的安装类问题。
能启动但不回复：
先看 03 的 Gateway / Control UI，再看 04 的模型配置。
平台收不到消息：
先看 05 的 channel 生命周期，再看 11 的消息平台问题。
AI 不按预期工作：
先看 06 的技能，再看 07 的记忆。
公网部署不放心：
先看 10，再回 09 检查 Docker 和反向代理。
⠀
每次排障都记录四件事：
⠀
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 分钟写：
⠀
# 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 没有意义。先运行：
⠀
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 助手”。
⠀
这个项目分四个阶段，不要求一天做完。
⠀
阶段一：本地个人助手
⠀
目标：
⠀
在本机启动 Gateway，用 Control UI 或 CLI 完成稳定对话。
⠀
涉及章节：
⠀
-
01 项目介绍
-
02 安装部署
-
03 快速开始
-
04 模型配置
⠀
你会留下：
⠀
- 当前安装方式。
- 当前 OpenClaw 版本。
- 默认模型。
- Gateway 启动命令。
- 第一条成功消息。
- 失败时看哪份日志。
⠀
这个阶段不要接公网，也不要做复杂多 Agent。你只需要证明“本机 -> Gateway -> 模型 -> 回复”这条线通了。
⠀
阶段二：手机入口助手
⠀
目标：
⠀
把 OpenClaw 接到 Telegram 或其他低摩擦消息平台。
⠀
涉及章节：
⠀
-
05 消息平台接入
-
10 安全配置的 DM Pairing
⠀
你会留下：
⠀
- 一个 Channel Runbook。
- Bot Token 存放位置。
- Pairing 策略。
- inbound / outbound 日志样例。
- 平台失效时的禁用方法。
⠀
这个阶段的重点不是"平台越多越好"，而是你能不能解释：消息从哪里来、谁能发、发给哪个 Agent、回复失败时查哪里。
⠀
阶段三：可复用工作能力
⠀
目标：
⠀
让 OpenClaw 做一个固定工作，例如整理反馈、生成会议纪要、分类 issue。
⠀
涉及章节：
⠀
-
06 技能系统
-
07 记忆系统
⠀
你会留下：
⠀
- 一个本地 Skill。
- 一个 examples/ 示例。
- 一份 USER.md 偏好。
- 一份 MEMORY.md 项目事实。
- 一条不写入敏感信息的规则。
⠀
这个阶段最容易犯的错，是把技能、记忆、模型混成一团。Skill 负责流程，Memory 负责长期上下文，模型负责生成和推理。它们不是同一件事。
⠀
阶段四：团队或服务器形态
⠀
目标：
⠀
把 OpenClaw 变成能长期运行、能备份、能恢复、能加固的服务。
⠀
涉及章节：
⠀
-
08 多 Agent 协作
-
09 Docker 部署
-
10 安全配置
-
11 FAQ
⠀
你会留下：
⠀
- 一个 Agent 分工草图。
- 一个 Docker Compose 或服务器运行手册。
- 一份备份恢复步骤。
- 一份安全事件处理笔记。
- 一份常见问题补充记录。
⠀
这个阶段才适合考虑多 Agent、Docker、反向代理、TLS、自动更新和长期日志。前面阶段没跑稳时，不要急着上服务器。
⠀
不同背景的人怎么读
⠀
完全新手
⠀
你可能不熟悉命令行、Node、API Key。先不要试图理解所有架构词。你的路线是：
⠀
00 -> 01 -> 02 -> 03 -> 11
⠀
读的时候只做三件事：
⠀
1. 跟着命令安装。
2. 跑通第一条消息。
3. 遇到错误记录原文。
⠀
暂时跳过：
⠀
- 多 Agent。
- Docker。
- 自定义插件。
- 公网部署。
⠀
个人效率用户
⠀
你关心的是手机入口、记忆和固定工作流。你的路线是：
⠀
00 -> 02 -> 03 -> 04 -> 05 -> 07 -> 06 -> 10
⠀
重点：
⠀
- Telegram / WebChat 入口。
- USER.md 里的沟通偏好。
- MEMORY.md 里的长期事实。
- 一个小 Skill。
- Pairing 和 token 安全。
⠀
暂时不要把 OpenClaw 拉进很多群。先让它成为你的个人助手，再考虑团队协作。
⠀
开源项目维护者
⠀
你关心社区支持、FAQ、issue 分拣和文档反馈。你的路线是：
⠀
00 -> 01 -> 03 -> 05 -> 06 -> 08 -> 10
⠀
重点：
⠀
- Discord / Slack 测试频道。
- community 和 tech-support 的边界。
- issue-triage Skill。
- 公开频道不输出敏感信息。
- 技术问题转交和日志追踪。
⠀
不要让 AI 直接关闭 issue、发布公告或承诺修复时间。先让它整理、解释、引导和生成草稿。
⠀
团队管理员
⠀
你关心权限、部署、审计、成本和可维护性。你的路线是：
⠀
00 -> 02 -> 04 -> 05 -> 08 -> 09 -> 10 -> 11
⠀
重点：
⠀
- 默认模型成本。
- 哪些频道可以触发。
- 哪些 Agent 有工具权限。
- Docker volume 和备份。
- Gateway 不直接暴露公网。
- token 轮换和事故处理。
⠀
团队场景里，OpenClaw 一个带入口、权限和数据边界的小系统。
⠀
插件或技能开发者
⠀
你关心扩展面、工具、Skill、MCP、插件兼容。你的路线是：
⠀
00 -> 01 -> 06 -> 07 -> 08 -> 10
⠀
重点：
⠀
- Skill 的触发和边界。
- Tool 与 Skill 的区别。
- 插件白名单。
- 第三方能力的权限最小化。
- 测试 Agent 和真实 Agent 分开。
⠀
开发者最容易低估安全边界。只要你的技能会读写文件、调用外部 API 或处理用户消息，就必须读安全章节。
⠀
课程笔记建议
⠀
建议你在自己的工作空间建一个学习目录：
⠀
mkdir -p ~/openclaw-learning
cd ~/openclaw-learning
⠀
每章建一份笔记：
⠀
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
⠀
每份笔记只记录四类内容：
⠀
# Chapter Note
## 我做了什么
...
## 当前配置
...
## 遇到的问题
...
## 下次继续
...
⠀
不要把教程全文复制一遍。笔记的价值是记录你自己的环境、选择和问题。
⠀
提问时怎么描述问题
⠀
无论你去 GitHub Issue、Discord、微信群，还是问 AI，描述问题时都尽量提供上下文。
⠀
模板：
⠀
## 我想做什么
...
## 我运行的命令
```bash
...
当前环境
- OS:
- Node:
- OpenClaw:
- Install method:
现象
...
日志关键行
...
我已经试过
...
⠀
一个好的问题描述能让别人直接判断问题在哪一层。只说“不能用”“不回复”“报错了”，通常会被迫来回追问。
⠀
## 30 天学习路线：从个人使用到可维护系统
⠀
如果你想系统学，而不是只临时查命令，可以按 30 天来安排。每天不需要很久，关键是每次只推进一个能力。
⠀
### 第 1 周：把最小链路跑稳
⠀
目标：
⠀
本地 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 周：接入一个真实入口
⠀
目标：
⠀
接入一个低风险消息平台，知道谁能发消息、消息进了哪个 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 周：让助手有工作能力
⠀
目标：
⠀
创建一个本地 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 周：走向团队和长期运行
⠀
目标：
⠀
知道什么时候需要多 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 分工、部署和安全笔记。
⠀
## 每周复盘问题
⠀
每周结束时，问自己这些问题：
⠀
- 这一周新增了哪个能力？
- 哪个配置变更最容易影响稳定性？
- 哪条日志最有排查价值？
- 有没有把敏感信息写入文档、日志或记忆？
- 如果明天换一台机器，我能不能恢复？
- 如果消息平台突然失效，我先看哪里？
- 如果模型费用升高，我先查哪个入口？
⠀
这些问题会把你从“会用命令”带到“会维护系统”。OpenClaw 的学习难点不是单条命令，而是多层链路同时存在：入口、Gateway、模型、Agent、Skill、Memory、安全和部署。
⠀
## 课程里的命令怎么读
⠀
文档里有很多命令。读命令时建议区分三类：
⠀
只读命令：
查看版本、状态、日志、配置。适合先运行。
配置命令：
修改模型、Channel、Agent、Skill。运行前记录原值。
高影响命令：
删除、重置、撤销 token、清理 volume、停服务。运行前确认备份和影响范围。
⠀
例子：
⠀
openclaw --version
openclaw channels status
openclaw models status
⠀
这些是只读命令，适合排查开头先跑。
⠀
openclaw config set agents.defaults.model openai/gpt-5.2-mini
⠀
这是配置命令，运行前最好先记录旧值：
⠀
openclaw config get agents.defaults.model
⠀
像下面这些就属于高影响动作：
⠀
docker compose down -v
openclaw reset
rm -rf ~/.openclaw
⠀
本教程会尽量把高影响动作写清楚，但你自己执行时也要先想：这会不会删除配置、记忆、凭证、volume 或会话历史？
⠀
## 按症状反查路线
⠀
OpenClaw 的问题常常表面相似。比如“Bot 不回复”可能是 Gateway 没启动、模型 Key 错、平台 token 失效、Pairing 没批准、路由给了错误 Agent，也可能只是平台限流。下面这张路线图适合排障时从症状反推。
⠀
### 症状一：命令行找不到 OpenClaw
⠀
先读：
⠀
02 安装部署 -> Node/npm/PATH/权限
⠀
先运行：
⠀
node --version
npm --version
npm prefix -g
echo $PATH
⠀
不要先做：
⠀
- 改 openclaw.json。
- 重新配置模型。
- 删除 ~/.openclaw。
⠀
这类问题通常还没进入 OpenClaw 配置层，而是在运行时和 shell 层。
⠀
### 症状二：Gateway 启动失败
⠀
先读：
⠀
03 快速开始 -> Gateway 管理
02 安装部署 -> 端口和配置排查
⠀
先运行：
⠀
openclaw doctor
lsof -i :18789 || ss -tlnp | grep 18789
openclaw gateway --port 18789 --verbose
⠀
判断：
⠀
端口占用：
先确认是不是旧 Gateway。
配置解析失败：
回到 openclaw.json 最近修改。
权限失败：
检查 ~/.openclaw 的 owner 和 chmod。
⠀
Gateway 是后面所有入口的基础。Gateway 没稳时，不要继续接 Telegram、Discord 或 Slack。
⠀
### 症状三：Control UI 能打开，但 AI 不回复
⠀
先读：
⠀
04 模型配置
03 快速开始 -> 日志和模型链路
⠀
先运行：
⠀
openclaw models status
openclaw config get agents.defaults.model
openclaw agent --message "请只回复 ok"
⠀
常见原因：
⠀
- API Key 未加载。
- 模型 ID 写错。
- provider 限流。
- 本地模型服务没启动。
- 上下文过长。
⠀
不要急着改 Agent。Agent 的表达方式会影响回答质量，但模型链路断了时，改 SOUL.md 没用。
⠀
### 症状四：Control UI 能聊，消息平台不回复
⠀
先读：
⠀
05 消息平台接入
10 安全配置 -> Pairing 和 token
⠀
先运行通道状态和对应平台日志；完整命令清单放在 OC-03 快速开始和 OC-10 安全排障里，本阅读指南只提醒排查顺序。
⠀
排查顺序：
⠀
- 平台 token 是否有效。
- Webhook / Polling 是否工作。
- 私聊是否需要 Pairing。
- 群聊是否需要 mention。
- channelId / guildId 是否匹配。
- 出站发送是否被平台限制。
⠀
这类问题说明 Gateway 和模型大概率是好的，坏在平台入口或出口。
⠀
### 症状五：AI 答得很怪，像忘了规则
⠀
先读：
⠀
06 技能系统
07 记忆系统
08 多 Agent 协作
⠀
先看：
⠀
openclaw skills list
openclaw memory status
⠀
再检查：
⠀
- 当前消息进了哪个 Agent。
- SOUL.md 是否具体。
- 是否触发了不相关 Skill。
- MEMORY.md 是否过期或冲突。
- 每日日志是否被误当成长期事实。
⠀
不要把这类问题都归因于“模型不行”。很多时候是上下文、技能或记忆给了模型错误信号。
⠀
### 症状六：Docker 更新后数据不见了
⠀
先读：
⠀
09 Docker 部署 -> volume 和恢复
02 安装部署 -> 安装方式切换
⠀
先运行：
⠀
docker compose ps
docker volume ls
docker inspect openclaw-gateway | grep -A 20 Mounts
⠀
重点判断：
⠀
- 有没有挂载 /home/node/.openclaw。
- 旧 volume 是否还在。
- compose 项目名是否变了。
- 是否运行过 docker compose down -v。
⠀
Docker 容器可以删，数据 volume 不能随便删。更新前备份，恢复前确认 volume 名称。
⠀
### 症状七：费用突然升高
⠀
先读：
⠀
04 模型配置 -> 成本控制
05 消息平台 -> 群聊费用和滥用控制
⠀
先查：
⠀
- 哪个入口触发最多。
- 哪个 Agent 使用强模型。
- 是否有自动任务循环。
- 是否有群聊所有消息都进模型。
- 是否有长上下文反复提交。
⠀
处理顺序：
⠀
- 暂停高频入口或改为 mention 触发。
- 高频 Agent 切到低成本模型。
- 限制长回答和自动摘要。
- 再分析是否需要强模型。
⠀
不要一上来把所有模型都换成最便宜的。成本控制要看任务类型，不是只看单价。
⠀
## 读完后的个人运行档案
⠀
建议你最终整理一份 OPENCLAW-RUNBOOK.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 这种长期运行工具，最怕所有知识都留在聊天记录里。
⠀
## 最后一张速查卡
⠀
当你忘了下一步该看哪章时，用这张卡：
⠀
装不上：
看 02。
能装但不会用：
看 03。
能聊但回答失败：
看 04。
平台不回复：
看 05。
想让它固定做一件事：
看 06。
想让它记住长期信息：
看 07。
想拆多个助手：
看 08。
想放服务器：
看 09。
担心安全和滥用：
看 10。
已经报错了：
看 11。
⠀
如果你只记住一句话：先把一条链路跑稳，再加下一层能力。OpenClaw 的学习顺序不是"功能越多越好"，而是每一层都知道怎么启动、怎么观察、怎么暂停、怎么恢复。
⠀
## 版本差异提醒
⠀
OpenClaw 更新很快，你本机命令的细节可能和文档略有差异。遇到这种情况，先看当前 CLI 的帮助，而不是硬套旧命令：
⠀
openclaw --help
openclaw channels --help
openclaw models --help
openclaw skills --help
⠀
如果帮助输出和教程不同，以当前安装版本为准，再把差异记录到自己的 Runbook。教程负责教你理解链路和排查方法，具体参数要跟随你正在运行的版本。
⠀
遇到命令不确定时，优先在本机看帮助，再回教程找上下文。这样既不会被旧参数卡住，也能把“这个命令属于哪一层”想清楚。
⠀
如果你把本机帮助输出和本教程的差异写进自己的运行档案，下一次升级、迁移或求助时会轻松很多。
记录差异时也写上日期和版本号，避免以后把旧环境经验误当成当前状态。
⠀
## 遇到问题怎么办？
⠀
1. 先看 11-常见问题FAQ，80% 的问题都有现成答案
1. 运行 openclaw doctor 让系统自动诊断
1. 到 GitHub Issues 搜索或提问
1. 加入 OpenClaw Discord 社区寻求帮助
---
## 文档约定
⠀
本套文档中使用以下标记：
⠀
标记
含义
🟢 入门
零基础可读
🟡 进阶
需要一点技术基础
🔴 高级
面向有经验的开发者
💡 提示
有用的小技巧
⚠️ 注意
容易踩的坑
🚫 危险
操作不当可能造成数据丢失或安全问题
📖 延伸阅读
想深入了解可以看这里
⏭️ 小白可跳过
新手不需要看这个章节