全书目录大纲（v2）

第一篇：入门（对应 wiki：入门）

第1章 WIKI 首页导读：先知道你要得到什么

1.1 OpenClaw 到底是什么

1.1.1 一句话解释 OpenClaw
1.1.2 它能做什么与不能做什么
1.1.3 最典型的个人使用场景

1.2 开始前你只需要准备三样

1.2.1 Node/npm（白话解释）
1.2.2 一个可用的模型 API Key
1.2.3 一台能执行命令的机器

1.3 5 分钟结果导向：先看到它回你一句

1.3.1 最短安装路径
1.3.2 最短启动路径
1.3.3 最小成功判据

1.4 架构图别硬啃：先看三块就够

1.4.1 输入端（聊天渠道）
1.4.2 中枢（Gateway）
1.4.3 执行端（Agent + Tools）

1.5 本书阅读路线图（新手版）

1.5.1 只想今天跑起来
1.5.2 想接入日常聊天工具
1.5.3 想让它稳定干活

第2章快速开始（照做就能跑）

2.1 环境检查：Node/npm/网络

2.1.1 Node 未安装时怎么安装
2.1.2 npm 与 pnpm 最小验证
2.1.3 网络与权限检查

2.2 安装 OpenClaw：最短路径

2.2.1 分步安装命令
2.2.2 常见安装报错处理
2.2.3 版本确认与回退

2.3 `openclaw onboard`：每一步在配什么

2.3.1 QuickStart 路径总览
2.3.2 Model/Auth 国内三家配置
2.3.3 Channel 先 Skip 的理由

2.4 首轮对话与验收

2.4.1 Hatch in WebUI/TUI 的选择
2.4.2 第一轮收发闭环
2.4.3 成功/失败判据

2.5 10 分钟排坑清单

2.5.1 命令找不到
2.5.2 鉴权失败
2.5.3 端口冲突

第3章核心概念（人话版）

3.1 Gateway/Agent/Session/Channel 一句话

3.1.1 Gateway 是“调度台”
3.1.2 Agent 是“执行大脑”
3.1.3 Session 与 Channel 的职责

3.2 Tools/Skills/Workspace 一句话

3.2.1 Tools 是“能力零件”
3.2.2 Skills 是“流程模板”
3.2.3 Workspace 是“工作台边界”

3.3 一条消息在系统里怎么走

3.3.1 入站与路由
3.3.2 推理与工具调用
3.3.3 回传与留痕

3.4 为什么你懂概念后，排障会快很多

3.4.1 改配置时知道改的是哪层
3.4.2 看报错时知道先查哪段
3.4.3 做扩展时知道动哪块

3.5 一图总览（记住就够用）

3.5.1 控制面与执行面
3.5.2 配置面与运行面
3.5.3 排障面与回滚面

第二篇：配置（对应 wiki：配置）

第4章频道配置总览（先选再配）

4.1 渠道选择：先按场景，不要按热度

4.1.1 个人场景推荐
4.1.2 团队场景推荐
4.1.3 新手避坑建议

4.2 WebChat：零门槛体验通道

4.2.1 打开方式
4.2.2 首轮会话
4.2.3 常见限制

4.3 Telegram：稳定入门线

4.3.1 Token 获取
4.3.2 接入流程
4.3.3 私聊/群聊策略

4.4 飞书：本书主线渠道

4.4.1 为什么主线选飞书
4.4.2 配置顺序总览
4.4.3 与第8章衔接

4.5 路由与会话隔离

4.5.1 私聊规则
4.5.2 群聊提及规则
4.5.3 多渠道会话隔离

第5章高级配置（openclaw.json 看得懂改得对）

5.1 配置分层与优先级

5.1.1 全局层
5.1.2 Agent 层
5.1.3 渠道层

5.2 关键字段最小解释

5.2.1 gateway
5.2.2 agents
5.2.3 channels/tools

5.3 workspace 与 state 的区别

5.3.1 数据归档边界
5.3.2 会话状态边界
5.3.3 备份边界

5.4 多环境配置（家用/公司/云）

5.4.1 家用最小配置
5.4.2 团队协作配置
5.4.3 云主机配置

5.5 改配置后的验收流程

5.5.1 config get/set/unset
5.5.2 doctor/status/logs
5.5.3 回滚与留痕

第6章模型接入与推理配置（国内读者优先）

6.1 `provider/model` 统一写法

6.1.1 写法规则
6.1.2 正确示例
6.1.3 典型误写

6.2 MiniMax / Z.AI / Moonshot 选择策略

6.2.1 能力与稳定性
6.2.2 延迟与成本
6.2.3 运维复杂度

6.3 主备模型与自动回退

6.3.1 primary/fallbacks 结构
6.3.2 触发条件
6.3.3 验证方法

6.4 密钥轮换与失效恢复

6.4.1 多 Key 策略
6.4.2 轮换顺序
6.4.3 失效应急

6.5 模型异常快速排查

6.5.1 unknown model
6.5.2 401/403
6.5.3 timeout/rate limit

第7章安全指南（新手也能执行）

7.1 最小权限基线

7.1.1 为什么先收权限
7.1.2 默认收敛策略
7.1.3 放权的前提条件

7.2 私聊/群聊/白名单

7.2.1 dmPolicy
7.2.2 requireMention
7.2.3 allowFrom

7.3 凭证与敏感信息管理

7.3.1 存放位置
7.3.2 权限设置
7.3.3 泄露处置

7.4 工具审批与沙箱

7.4.1 approvals
7.4.2 sandbox 模式
7.4.3 风险工具默认策略

7.5 成本与频率控制

7.5.1 预算上限
7.5.2 限流策略
7.5.3 监控与告警

第8章飞书接入实战（截图版）

8.1 飞书开放平台准备

8.1.1 创建应用
8.1.2 权限与事件
8.1.3 发布前检查

8.2 `openclaw channels add` 实操

8.2.1 命令顺序
8.2.2 App ID/Secret 填写
8.2.3 落盘验证

8.3 发布与长连接订阅顺序

8.3.1 为什么先发布
8.3.2 长连接订阅步骤
8.3.3 失败排查

8.4 配对放行与消息闭环

8.4.1 pairing 列表
8.4.2 approve 放行
8.4.3 闭环验收

8.5 常见报错与修复

8.5.1 插件安装失败
8.5.2 回调/订阅失败
8.5.3 消息不回

第三篇：Tools & Skills（对应 wiki：工具与技能）

第9章 Tools 全景图（先认识再上手）

9.1 Tools 与 Skills 的关系

9.1.1 Tool 是能力
9.1.2 Skill 是流程
9.1.3 二者协作方式

9.2 常用工具组与用途

9.2.1 文件与命令
9.2.2 Web 与浏览器
9.2.3 多模态工具

9.3 工具权限边界怎么收紧

9.3.1 allow/deny
9.3.2 profile 策略
9.3.3 风险分级

9.4 工具日志怎么看

9.4.1 调用链
9.4.2 错误点
9.4.3 回放点

9.5 新手最稳组合

9.5.1 起步组合
9.5.2 进阶组合
9.5.3 生产组合

第10章 Skills 安装与第一个实战（从 0 到 1）

10.1 先安装再动手

10.1.1 clawhub search
10.1.2 clawhub install
10.1.3 openclaw skills list --eligible

10.2 选题与边界

10.2.1 低风险高复用题目
10.2.2 输入输出边界
10.2.3 失败语义边界

10.3 最小闭环实现

10.3.1 SKILL.md 最小结构
10.3.2 首次调用验收
10.3.3 失败重试验收

10.4 幂等/重试/限流

10.4.1 幂等策略
10.4.2 重试策略
10.4.3 限流策略

10.5 发布与更新

10.5.1 文档最小清单
10.5.2 clawhub update --all
10.5.3 发布后验收

第11章 Skills 工程化（从能用到稳用）

11.1 结构化 I/O 与可测试性

11.1.1 输入契约
11.1.2 输出契约
11.1.3 回归用例

11.2 会话一致性与可回放

11.2.1 会话键设计
11.2.2 日志与回放
11.2.3 清理策略

11.3 超时、降级与熔断

11.3.1 超时阈值
11.3.2 降级路径
11.3.3 熔断阈值

11.4 成本与频率控制

11.4.1 频率限制
11.4.2 成本预算
11.4.3 异常告警

11.5 失败可解释设计

11.5.1 错误提示模板
11.5.2 修复建议模板
11.5.3 用户反馈闭环

第四篇：进阶（对应 wiki：平台/部署/排障）

第12章平台指南（macOS/iOS/Android/Canvas）

12.1 macOS App 能力

12.1.1 菜单栏能力
12.1.2 Voice Wake
12.1.3 系统集成

12.2 iOS/Android 节点接入

12.2.1 节点配对
12.2.2 相机与录屏
12.2.3 移动端限制

12.3 Canvas 能力

12.3.1 present/navigate/snapshot
12.3.2 典型场景
12.3.3 常见问题

12.4 语音与系统工具

12.4.1 语音链路
12.4.2 系统命令
12.4.3 权限边界

12.5 平台问题速查

12.5.1 权限弹窗
12.5.2 后台限制
12.5.3 节点失联

第13章部署与运维（本地到云主机）

13.1 部署形态怎么选

13.1.1 本地部署
13.1.2 云主机部署
13.1.3 Docker 部署

13.2 远程访问

13.2.1 Tailscale
13.2.2 SSH 隧道
13.2.3 安全建议

13.3 服务守护与自启动

13.3.1 macOS LaunchAgent
13.3.2 Linux systemd
13.3.3 运行态检查

13.4 升级与回滚

13.4.1 升级前检查
13.4.2 升级后验收
13.4.3 回滚策略

13.5 日常维护清单

13.5.1 日检
13.5.2 周检
13.5.3 月检

第14章故障排查手册（从现象到根因）

14.1 五步诊断法

14.1.1 status
14.1.2 doctor
14.1.3 logs

14.2 安装与启动问题

14.2.1 命令不存在
14.2.2 启动失败
14.2.3 端口冲突

14.3 模型/渠道/权限问题

14.3.1 模型鉴权
14.3.2 渠道连通
14.3.3 权限拒绝

14.4 技能执行异常

14.4.1 eligible 缺失
14.4.2 依赖缺失
14.4.3 输出异常

14.5 重大故障应急流程

14.5.1 快速止血
14.5.2 回滚恢复
14.5.3 复盘改进

第五篇：补充章（速查与全渠道索引）

第15章补充章：CLI 与全渠道速查

15.1 CLI 高频命令速查

15.1.1 安装与启动
15.1.2 配置与诊断
15.1.3 频道与技能

15.2 内置渠道最小接入

15.2.1 Telegram
15.2.2 WhatsApp
15.2.3 Discord/Slack/WebChat

15.3 插件渠道最小接入

15.3.1 Mattermost
15.3.2 Matrix/Nextcloud Talk/Nostr
15.3.3 LINE/Zalo/Teams/Tlon/Twitch

15.4 通用排障顺序

15.4.1 插件与配置
15.4.2 网关与日志
15.4.3 回退与恢复

15.5 官方文档索引

15.5.1 channels 索引
15.5.2 cli 索引
15.5.3 troubleshooting 索引