OpenClaw 入门到进阶教程大纲

基于 OpenClaw 官方文档整理，涵盖从零开始到高级运维的完整学习路径。

第一部分：认识 OpenClaw

第 1 章：OpenClaw 是什么

1.1 项目定位：多渠道 AI 智能体网关平台
1.2 核心能力概览
- 统一接入 WhatsApp、Telegram、Discord、Slack、Signal、iMessage 等 20+ 消息平台
- 内置 AI 智能体运行时（基于 pi-mono）
- 多智能体并行与路由
- 工具执行、浏览器自动化、定时任务
1.3 架构总览
- 单一长驻 Gateway 设计
- WebSocket 协议通信（Control-plane / Nodes / WebChat）
- 请求-响应帧格式：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
- 设备配对与信任模型
依据：concepts/architecture — "single long-lived Gateway that owns all messaging surfaces"

第 2 章：支持的平台与运行环境

2.1 macOS（原生应用 + 菜单栏集成）
2.2 Linux（命令行部署）
2.3 Windows（通过 WSL2）
2.4 iOS / Android 节点应用
2.5 Docker 容器化部署
2.6 云平台部署：Fly.io / Railway / Render / Hetzner / GCP / Northflank
依据：platforms/ 与 install/ 目录下各平台文档

第二部分：快速上手

第 3 章：安装与初始化

3.1 前置条件：Node.js 22+
3.2 一键安装脚本（macOS/Linux bash、Windows PowerShell）
3.3 运行引导向导：openclaw onboard --install-daemon
- 配置认证（API Key / OAuth）
- 选择模型提供商
- 可选：绑定消息渠道
3.4 验证网关状态：openclaw gateway status
3.5 环境变量配置
- OPENCLAW_HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH
依据：start/getting-started — 三步安装流程

第 4 章：第一次对话

4.1 零配置体验：openclaw dashboard → 访问 http://127.0.0.1:18789/
4.2 通过 CLI 发送测试消息：openclaw message
4.3 Control UI 界面导览
- 会话列表、消息输入、模型切换
4.4 理解会话（Session）的概念
- 主会话 vs 隔离会话
- 会话生命周期与重置
依据：start/getting-started — "Launch Control UI without channel configuration"

第 5 章：连接你的第一个消息渠道

5.1 Telegram（最快上手，Bot Token 即可）
5.2 WhatsApp（QR 码配对，Baileys 协议）
5.3 Discord（Bot 应用 + Token）
5.4 渠道通用概念
- DM 策略：pairing / allowlist / open / disabled
- 群组消息：requireMention 提及门控
- allowFrom 白名单机制
依据：channels/index — "WhatsApp — Most popular; uses Baileys and requires QR pairing"；channels/telegram

第三部分：核心概念深入

第 6 章：智能体（Agent）运行时

6.1 Pi-mono 智能体引擎
6.2 工作区（Workspace）：agents.defaults.workspace
6.3 Bootstrap 启动文件体系（首次会话注入）
- AGENTS.md — 操作指引与记忆
- SOUL.md — 人格定义与边界
- TOOLS.md — 工具文档
- BOOTSTRAP.md — 一次性初始化（执行后自动删除）
- IDENTITY.md — 名称与角色
- USER.md — 用户画像
6.4 智能体执行循环（Agent Loop）
依据：concepts/agent — "six user-editable files injected on first session startup"

第 7 章：会话管理

7.1 会话作用域
- per-sender：按发送者隔离
- dmScope 选项：main / per-peer / per-channel-peer / per-account-channel-peer
7.2 会话存储：~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl
7.3 会话重置策略
- 按时间：每日固定时刻重置
- 按空闲：闲置 N 分钟后重置
7.4 会话修剪（Pruning）：30 天自动清理，500 条上限，10MB 轮转
7.5 上下文压缩（Compaction）
依据：concepts/session、concepts/session-pruning、concepts/compaction

第 8 章：记忆系统

8.1 设计哲学："写入磁盘才是记忆"
8.2 两层记忆结构
- 日志层：memory/YYYY-MM-DD.md（每日追加）
- 长期层：MEMORY.md（仅私聊加载，群聊不加载）
8.3 自动记忆刷写：上下文压缩前静默触发
8.4 向量语义搜索：支持 OpenAI / Gemini / Voyage / 本地模型嵌入
8.5 QMD 后端（实验性）：BM25 + 向量混合检索
8.6 memory_search / memory_get 工具
依据：concepts/memory — "plain Markdown files as the authoritative source"

第 9 章：模型提供商配置

9.1 内置提供商：Anthropic / OpenAI / Google Gemini / Groq / xAI / OpenRouter
9.2 模型引用格式：provider/model（如 anthropic/claude-opus-4-6）
9.3 自定义提供商配置（models.providers）
- 兼容 OpenAI 协议的任何服务（Ollama、LM Studio、vLLM、LiteLLM）
- Moonshot AI (Kimi)、MiniMax、Z.AI GLM 等国产模型
9.4 模型故障转移（Model Failover）
9.5 OAuth 订阅认证（Anthropic / OpenAI）
9.6 CLI 模型管理：openclaw models list / openclaw models set
依据：concepts/model-providers、providers/ 目录

第 10 章：消息处理与路由

10.1 消息队列模式：collect / steer / followup / interrupt
10.2 入站消息防抖：messages.inbound.debounceMs
10.3 响应前缀模板：{model}、{identity.name} 等变量
10.4 确认反应表情：messages.ackReaction
10.5 流式输出与分块
- 段落 / 换行 / 句子断点
- 合并减少消息刷屏
- 模拟人类打字延迟
10.6 Markdown 格式化支持
10.7 打字指示器（Typing Indicators）
依据：concepts/messages、concepts/streaming、concepts/typing-indicators

第四部分：工具与能力扩展

第 11 章：内置工具体系

11.1 工具分类总览
- 执行类：exec、process、apply_patch
- 信息类：web_search、web_fetch
- 浏览器类：browser、canvas
- 会话类：sessions_list / sessions_history / sessions_send / sessions_spawn
- 跨渠道消息：message
- 节点设备：nodes
- 自动化：cron、gateway
- 记忆类：memory_search、memory_get
11.2 工具组快捷语法：group:fs / group:runtime / group:messaging / group:web 等
11.3 工具策略配置
- tools.allow / tools.deny
- 内置策略模板：minimal / coding / messaging / full
依据：tools/index — 完整工具清单

第 12 章：浏览器自动化

12.1 两种控制模式
- OpenClaw 托管浏览器（推荐，隔离 Chromium 实例）
- Chrome 扩展中继（复用已有浏览器）

12.2 快速上手

bash

openclaw browser --browser-profile openclaw start
openclaw browser open https://example.com
openclaw browser snapshot
openclaw browser click 12

12.3 Ref 系统：AI 快照（数字 Ref）vs 角色快照（e12）
12.4 多 Profile 管理
12.5 远程 CDP 连接（Browserless 等）
12.6 安全注意事项：隔离 Profile、避免暴露登录态
依据：tools/browser — "dedicated, isolated browser for agent automation"

第 13 章：技能（Skills）系统

13.1 技能是什么：AgentSkills 兼容的指令文件夹
13.2 SKILL.md 文件格式（YAML 前言 + Markdown 指令）
13.3 三级加载优先级
- 工作区技能（最高）→ 托管技能（~/.openclaw/skills）→ 内置技能
13.4 技能门控：requires.bins / requires.env / requires.config / OS 过滤
13.5 ClawHub 公共注册表：clawhub install <skill-slug>
13.6 技能配置与安全：skills.entries 中的 apiKey、env 注入
依据：tools/skills — "AgentSkills-compatible skill folders"

第 14 章：Hooks 事件钩子

14.1 Hooks vs Webhooks 的区别
14.2 四个内置 Hook
- session-memory：/new 时保存会话快照
- command-logger：命令审计日志
- boot-md：网关启动时执行工作区指令
- soul-evil：条件性内容替换
14.3 自定义 Hook 开发
- 目录结构：HOOK.md + handler.ts
- 事件类型：command:new / command:reset / agent:bootstrap / gateway:startup
14.4 Hook 管理：openclaw hooks list / enable / disable
依据：automation/hooks — "event-driven automation system"

第 15 章：定时任务（Cron）

15.1 Gateway 内置调度器
15.2 三种调度方式
- at：一次性（ISO 8601 时间戳）
- every：固定间隔（毫秒）
- cron：标准 5 字段 cron 表达式 + IANA 时区
15.3 执行模式：主会话注入 vs 隔离会话
15.4 任务交付：渠道通知（Slack/Discord/Telegram 等）或静默执行
15.5 CLI 管理：openclaw cron add / list / run
依据：automation/cron-jobs — "Gateway's built-in scheduler"

第五部分：多智能体与高级路由

第 16 章：多智能体架构

16.1 "每个智能体是一个完全隔离的大脑"
- 独立工作区、独立认证、独立会话
16.2 在 agents.list[] 中定义多个智能体
16.3 每智能体独立配置
- 认证文件：<agentDir>/auth-profiles.json
- 会话存储：~/.openclaw/agents/<agentId>/sessions/
- 沙箱策略、工具白名单
依据：concepts/multi-agent — "fully scoped brain with independent workspaces"

第 17 章：消息路由规则

17.1 确定性绑定规则（按优先级）
1. Peer 匹配（DM / 群组 / 频道 ID）
2. Guild / Team ID
3. Account ID
4. 渠道级匹配
5. 默认智能体兜底
17.2 实战场景
- 同一 WhatsApp 号码，不同联系人路由到不同智能体
- WhatsApp 用快模型、Telegram 用强模型
- 特定群组绑定专属智能体 + 提及门控
17.3 多账号支持：accountId 区分多个登录实例
依据：concepts/multi-agent — "Peer bindings always win"

第 18 章：子智能体与智能体间通信

18.1 sessions_spawn：创建子会话
18.2 sessions_send：跨会话消息传递
18.3 agents_list：枚举可用智能体
18.4 agent-send 工具：智能体间消息发送
18.5 LLM 任务委派：llm-task 工具
依据：tools/subagents、tools/agent-send、tools/llm-task

第六部分：安全与沙箱

第 19 章：安全模型与最佳实践

19.1 三层访问控制原则
1. 身份优先：谁能联系机器人
2. 作用域：机器人能在哪操作
3. 模型最后：假设模型可被操纵，限制爆炸半径
19.2 DM 策略详解：pairing（默认）→ allowlist → open
19.3 网络绑定安全层级
- loopback（最安全）→ Tailscale Serve → LAN + 防火墙 → 永远不要暴露 0.0.0.0
19.4 网关认证：Token 模式（推荐） / Password 模式
19.5 文件权限硬化：~/.openclaw/ → 700，openclaw.json → 600
19.6 安全审计命令：openclaw security audit [--deep] [--fix]
依据：gateway/security/index — "access control before intelligence"

第 20 章：提示词注入防御

20.1 现实认知："提示词注入尚未解决"
20.2 硬性防御手段：工具策略 + 审批机制 + 沙箱 + 白名单
20.3 危险信号识别
- "阅读这个文件/URL 并照做"
- "忽略你的系统提示"
- 请求暴露隐藏指令
20.4 缓解策略
- 使用最新最强模型
- 为不可信内容启用"阅读者智能体"（禁用工具）
- 严格控制 web_search / web_fetch / browser 的开启范围
20.5 真实事故案例
- "find ~ 事件"：用户请求导致主目录泄露到群聊
- "发现真相攻击"：社会工程诱导文件系统探索
依据：gateway/security/index — "Prompt injection is not solved"

第 21 章：Docker 沙箱化

21.1 两种沙箱策略
- 整体容器化：Gateway 运行在 Docker 内
- 工具沙箱：Gateway 在宿主机，工具在容器中执行
21.2 沙箱模式配置
- mode：off / non-main / all
- scope：session（每会话）/ agent（每智能体）/ shared
- workspaceAccess：none / ro / rw
21.3 默认安全姿态：node 用户、只读根文件系统、无网络、受限进程
21.4 三种沙箱镜像
- 基础沙箱
- 常用工具变体（Node / Go / Rust）
- 浏览器变体（Chromium + noVNC）
21.5 资源限制：内存 1GB / CPU 1 核 / 进程 256 PID
依据：gateway/sandboxing、install/docker

第七部分：部署与运维

第 22 章：生产环境部署

22.1 Docker Compose 部署
- docker-setup.sh 一键脚本
- 环境变量：OPENCLAW_DOCKER_APT_PACKAGES / OPENCLAW_EXTRA_MOUNTS / OPENCLAW_HOME_VOLUME
22.2 云平台部署指南
- Fly.io / Railway / Render / Northflank
- GCP / Hetzner
22.3 Ansible 自动化部署
22.4 Nix 包管理器安装
依据：install/docker、install/ 目录

第 23 章：远程访问

23.1 Tailscale 集成（推荐方案）
23.2 SSH 隧道
23.3 远程网关部署
23.4 Bonjour 服务发现
23.5 网络模型与连接方式
依据：gateway/remote、gateway/tailscale、gateway/network-model

第 24 章：监控与故障排查

24.1 健康检查系统：openclaw health
24.2 心跳监控（Heartbeat）
24.3 日志系统配置
- 日志级别、文件位置、敏感信息脱敏
- 日志路径：/tmp/openclaw/openclaw-YYYY-MM-DD.log
24.4 诊断工具：openclaw doctor --fix
24.5 常见问题排查
- 网关无法启动 → 配置校验失败
- 渠道连接中断 → 检查凭据与网络
- 工具执行失败 → 权限与沙箱配置
24.6 事故响应清单
1. 遏制：停止网关 → 切回 loopback → 禁用高风险渠道
2. 轮换：网关 Token → 客户端密钥 → 提供商凭据
3. 审计：检查日志 → 会话记录 → 配置变更 → openclaw security audit --deep
依据：gateway/troubleshooting、gateway/health、gateway/security/index

第 25 章：配置管理进阶

25.1 配置文件位置与格式：~/.openclaw/openclaw.json（JSON5）
25.2 配置分割：$include 指令实现多文件深度合并
25.3 环境变量替换：${VAR_NAME} 语法
25.4 .env 文件加载优先级
25.5 配置校验：严格 Schema，未知键导致启动拒绝
25.6 原子化配置更新：config.apply RPC / config.patch 局部更新
25.7 配置示例集锦
- 最小配置
- 多智能体路由配置
- 自聊模式配置
依据：gateway/configuration — "OpenClaw only accepts configurations that fully match the schema"

第八部分：移动端与节点

第 26 章：节点（Nodes）系统

26.1 节点概念：iOS / Android / macOS 客户端设备
26.2 设备配对流程
26.3 Canvas 画布功能
26.4 节点能力
- 摄像头捕获
- 音频与语音笔记（含转写）
- 位置查询
- Talk 模式（实时语音交互）
- 语音唤醒（VoiceWake）
26.5 节点故障排查
依据：nodes/ 目录

第 27 章：macOS 原生应用

27.1 菜单栏集成
27.2 内置网关（Bundled Gateway）
27.3 Peekaboo 桥接
27.4 语音覆盖层 UI
27.5 XPC 进程间通信
27.6 权限管理
依据：platforms/mac/ 目录

第九部分：进阶主题

第 28 章：Web 界面体系

28.1 Control UI 控制面板
28.2 Dashboard 仪表盘
28.3 WebChat 远程聊天界面
28.4 TUI 终端界面
依据：web/ 目录

第 29 章：更多消息渠道接入

29.1 Slack（Workspace 应用集成）
29.2 Signal（安全通讯）
29.3 iMessage / BlueBubbles（推荐完整功能支持）
29.4 Matrix（去中心化协议）
29.5 Mattermost / Microsoft Teams / Google Chat
29.6 IRC / LINE / Feishu（飞书）/ Zalo
29.7 广播组（Broadcast Groups）
29.8 渠道路由逻辑
依据：channels/ 目录完整列表

第 30 章：Webhook 与外部集成

30.1 Webhook 处理：外部系统触发 OpenClaw
30.2 Gmail Pub/Sub 集成
30.3 轮询机制（Poll）
30.4 认证监控自动化
依据：automation/webhook、automation/gmail-pubsub、automation/poll

第 31 章：插件与扩展开发

31.1 插件系统：tools/plugin
31.2 Slash 命令系统
31.3 Lobster：类型化工作流运行时（可组合管道 + 审批门控）
31.4 OpenAI 兼容 HTTP API
31.5 工具调用 HTTP API
31.6 RPC 适配器
依据：tools/plugin、tools/lobster、gateway/openai-http-api、reference/rpc

第 32 章：高级安全话题

32.1 形式化验证与安全模型
32.2 沙箱 vs 工具策略 vs 提权模式对比
32.3 提权执行（Elevated）：显式逃出沙箱
32.4 多智能体安全隔离配置实例
- 个人智能体：全权限、无沙箱
- 家庭/工作智能体：沙箱 + 只读文件系统
- 公开智能体：沙箱 + 仅消息工具
32.5 密钥扫描与 CI 集成：detect-secrets
依据：security/formal-verification、gateway/sandbox-vs-tool-policy-vs-elevated

第十部分：CLI 命令速查与参考

第 33 章：CLI 完整命令参考

33.1 网关管理：gateway / health / status / doctor
33.2 智能体管理：agent / agents
33.3 渠道管理：channels / pairing
33.4 会话管理：sessions
33.5 模型管理：models
33.6 记忆管理：memory
33.7 配置管理：configure / setup
33.8 自动化：cron / hooks
33.9 安全与诊断：security / doctor / logs
33.10 其他：browser / nodes / plugins / skills / sandbox / tui / dashboard / update / uninstall
依据：cli/ 目录完整命令列表

第 34 章：模板文件参考

34.1 AGENTS.md 默认模板
34.2 SOUL.md 人格模板
34.3 IDENTITY.md 身份模板
34.4 USER.md 用户模板
34.5 BOOTSTRAP.md 引导模板
34.6 HEARTBEAT.md 心跳模板
34.7 TOOLS.md 工具模板
34.8 BOOT.md 启动模板
依据：reference/templates/ 目录

附录

附录 A：常见问题（FAQ）

依据：help/faq

附录 B：环境变量完整参考

依据：help/environment

附录 C：Token 用量与成本追踪

依据：reference/token-use

附录 D：贡献指南

提交 Issue：help/submitting-an-issue
提交 PR：help/submitting-a-pr
测试流程：help/testing
CI 管道：ci

附录 E：社区展示与案例

依据：start/showcase — "Real-world OpenClaw projects from the community"

本大纲基于 OpenClaw 官方文档站 https://docs.openclaw.ai/ 的完整内容结构编写，每个章节标注了对应的文档来源依据。

OpenClaw 入门到进阶教程大纲 ​

第一部分：认识 OpenClaw ​

第 1 章：OpenClaw 是什么 ​

第 2 章：支持的平台与运行环境 ​

第二部分：快速上手 ​

第 3 章：安装与初始化 ​

第 4 章：第一次对话 ​

第 5 章：连接你的第一个消息渠道 ​

第三部分：核心概念深入 ​

第 6 章：智能体（Agent）运行时 ​

第 7 章：会话管理 ​

第 8 章：记忆系统 ​

第 9 章：模型提供商配置 ​

第 10 章：消息处理与路由 ​

第四部分：工具与能力扩展 ​

第 11 章：内置工具体系 ​

第 12 章：浏览器自动化 ​

第 13 章：技能（Skills）系统 ​

第 14 章：Hooks 事件钩子 ​

第 15 章：定时任务（Cron） ​

第五部分：多智能体与高级路由 ​

第 16 章：多智能体架构 ​

第 17 章：消息路由规则 ​

第 18 章：子智能体与智能体间通信 ​

第六部分：安全与沙箱 ​

第 19 章：安全模型与最佳实践 ​

第 20 章：提示词注入防御 ​

第 21 章：Docker 沙箱化 ​

第七部分：部署与运维 ​

第 22 章：生产环境部署 ​

第 23 章：远程访问 ​

第 24 章：监控与故障排查 ​

第 25 章：配置管理进阶 ​

第八部分：移动端与节点 ​

第 26 章：节点（Nodes）系统 ​

第 27 章：macOS 原生应用 ​

第九部分：进阶主题 ​

第 28 章：Web 界面体系 ​

第 29 章：更多消息渠道接入 ​

第 30 章：Webhook 与外部集成 ​

第 31 章：插件与扩展开发 ​

第 32 章：高级安全话题 ​

第十部分：CLI 命令速查与参考 ​

第 33 章：CLI 完整命令参考 ​

第 34 章：模板文件参考 ​

附录 ​

附录 A：常见问题（FAQ） ​

附录 B：环境变量完整参考 ​

附录 C：Token 用量与成本追踪 ​

附录 D：贡献指南 ​

附录 E：社区展示与案例 ​

OpenClaw 入门到进阶教程大纲

第一部分：认识 OpenClaw

第 1 章：OpenClaw 是什么

第 2 章：支持的平台与运行环境

第二部分：快速上手

第 3 章：安装与初始化

第 4 章：第一次对话

第 5 章：连接你的第一个消息渠道

第三部分：核心概念深入

第 6 章：智能体（Agent）运行时

第 7 章：会话管理

第 8 章：记忆系统

第 9 章：模型提供商配置

第 10 章：消息处理与路由

第四部分：工具与能力扩展

第 11 章：内置工具体系

第 12 章：浏览器自动化

第 13 章：技能（Skills）系统

第 14 章：Hooks 事件钩子

第 15 章：定时任务（Cron）

第五部分：多智能体与高级路由

第 16 章：多智能体架构

第 17 章：消息路由规则

第 18 章：子智能体与智能体间通信

第六部分：安全与沙箱

第 19 章：安全模型与最佳实践

第 20 章：提示词注入防御

第 21 章：Docker 沙箱化

第七部分：部署与运维

第 22 章：生产环境部署

第 23 章：远程访问

第 24 章：监控与故障排查

第 25 章：配置管理进阶

第八部分：移动端与节点

第 26 章：节点（Nodes）系统

第 27 章：macOS 原生应用

第九部分：进阶主题

第 28 章：Web 界面体系

第 29 章：更多消息渠道接入

第 30 章：Webhook 与外部集成

第 31 章：插件与扩展开发

第 32 章：高级安全话题

第十部分：CLI 命令速查与参考

第 33 章：CLI 完整命令参考

第 34 章：模板文件参考

附录

附录 A：常见问题（FAQ）

附录 B：环境变量完整参考

附录 C：Token 用量与成本追踪

附录 D：贡献指南

附录 E：社区展示与案例