OpenClaw 从入门到精通（V3版大纲）

全书定位

一本面向国内零基础读者的 OpenClaw 使用手册，覆盖官方 Guidebook 全部内容，重点突出飞书接入和国产大模型（KIMI、MiniMax、GLM）配置。

写作风格

• 通俗易懂：用生活化比喻解释技术概念，术语首次出现必解释
• 风趣幽默：适当轻松吐槽，但不低俗、不涉政
• 接地气：承认读者会遇到的真问题（“一装就报错”），给出真实解决方案
• 由浅入深：先让读者看到结果，再解释原理，最后给进阶选项

核心原则

1. 先给”能跑起来”的路径：每章开头明确告诉读者”学完这章你能做什么”
2. 一页只解决一件事：不堆砌概念，每个小节目标单一明确
3. 照抄就能跑：所有命令经过实测，关键步骤配截图说明位置
4. 先通飞书，再谈其他：第3章就开始讲飞书，满足国内读者核心需求

---

第一部分：初识（读完这部分，你会说”原来如此”）

第1章 3分钟搞懂：OpenClaw 到底是什么

本章目标：让读者在3分钟内理解 OpenClaw 的核心价值，产生”这玩意儿对我有用”的共鸣

章节结构：

• 1.1 一句话解释：你的AI助理，住在你的电脑里
• 1.2 它能做什么：三个真实场景（自动整理日报、查资料写报告、飞书里@它办事）
• 1.3 它不是什么：澄清常见误解（不是ChatGPT替代品、不是云端服务、不会自己上网乱买东西）
• 1.4 为什么2026年它突然火了：工程化的可用性拐点
• 1.5 阅读路线图：三种读者的最短路径

风格要点：用”带工具箱的实习生”类比Agent，用”总调度室”类比Gateway

---

第2章 准备工作：你只需要这三样东西

本章目标：降低心理门槛，让读者确认”我具备开始的条件”

章节结构：

• 2.1 一台电脑（Windows/Mac/Linux都行，有网就行）
• 2.2 一个API Key（别被这个词吓到，就是一串密码）
  • 推荐路径：KIMI/MiniMax/GLM Coding Plan（国内友好）
  • 备选路径：本书不展开（先跑通国内主线）
• 2.3 10分钟时间（和一点点耐心）
• 2.4 提前看看你会得到什么：截图预览最终效果

风格要点：用”别慌”开头，解释API Key时用”就像饭店的VIP卡”类比

---

第二部分：跑起来（读完这部分，你已经能跟AI对话了）

第3章 5分钟安装：照着点就行

本章目标：让读者用最短时间完成安装并发出第一条消息

章节结构：

• 3.1 环境检查：Node.js是什么？怎么装？
• 3.2 安装命令：就一行，复制粘贴
• 3.3 运行向导：openclaw onboard每一步在问什么
  • QuickStart vs Manual 怎么选
  • Model/Auth 配置：国内三家Coding Plan详解
  • 为什么Channel先选”Skip”
• 3.4 验证成功：看到Web UI长什么样
• 3.5 发第一条消息：“你好，请介绍一下你自己”

风格要点：每一步配”如果出错了怎么办”小框，用”别怕”安抚焦虑

---

第4章 10分钟排坑：当事情不顺利时

本章目标：覆盖最高频的5个报错，让读者有”遇到问题不慌”的信心

章节结构：

• 4.1 “command not found”：PATH问题，重开终端就能解决
• 4.2 端口被占用：谁占了18789？怎么换端口？
• 4.3 401/403错误：Key没配对、额度用完了、网络不通
• 4.4 页面打开了但不出回复：模型没配好、网络代理问题
• 4.5 Windows用户的特殊注意事项：WSL2是你的朋友

风格要点：用”排坑清单”形式，每个问题给”一眼症状→可能原因→解决动作”

---

第三部分：接上飞书（读完这部分，你在公司里能@AI干活了）

第5章 飞书接入：从0到能@机器人

本章目标：详细、可复现的飞书接入全流程，保留已验证的时序经验

章节结构：

• 5.1 飞书开放平台：创建企业应用（截图每一步）
• 5.2 获取凭证：App ID和App Secret在哪里
• 5.3 权限配置：批量导入那一大串权限
• 5.4 发布应用：为什么要先发布？（实测验证的关键时序）
• 5.5 OpenClaw侧配置：openclaw channels add交互式配置
• 5.6 关键时序：先发布→再配置→再开长连接（实测经验）
• 5.7 开启事件订阅：长连接+im.message.receive_v1
• 5.8 配对与放行：openclaw pairing list feishu + openclaw pairing approve feishu <CODE>
• 5.9 验收：私聊通了，再玩群聊@它

风格要点：用”切记”强调时序重要性，用”截图”明确每个按钮位置

---

第6章 飞书进阶：别让它乱回消息

本章目标：让读者掌握飞书渠道的安全配置，避免”机器人乱回”的尴尬

章节结构：

• 6.1 私聊策略：pairing/allowlist/all 的区别
• 6.2 群聊策略：requireMention的重要性
• 6.3 白名单配置：allowFrom/groupAllowFrom
• 6.4 风控 checklist：上线前的5个检查项
• 6.5 常见问题：长连接订阅失败、消息不回、@没反应

风格要点：用”血的教训”引出安全建议，但不制造焦虑

---

第四部分：配置深入（读完这部分，你知道怎么调教它了）

第7章 模型配置：KIMI、MiniMax、GLM怎么选

本章目标：详细讲解国内三家Coding Plan的配置，这是国内读者最关心的

章节结构：

• 7.1 三家对比：能力、速度、成本、稳定性
• 7.2 KIMI Coding Plan配置：从订阅到Key获取到配置
• 7.3 MiniMax Coding Plan配置：OAuth vs API Key路径
• 7.4 GLM Coding Plan配置：Bigmodel控制台操作
• 7.5 模型切换与回退：primary/fallbacks配置
• 7.6 成本监控：别让它刷爆你的卡

风格要点：用表格对比三家，给出”我的建议”

---

第8章 配置文件：openclaw.json 解剖

本章目标：让读者理解配置文件的层次结构，能独立修改配置

章节结构：

• 8.1 配置文件在哪里：路径与编辑方式
• 8.2 配置分层：全局→Agent→Channel的优先级
• 8.3 关键字段详解：gateway、agents、channels、tools
• 8.4 多环境配置：家用/公司/云主机
• 8.5 修改后的验证：config get/set、doctor、status

风格要点：用”配置不是编程”降低恐惧，用”改前备份”强调安全

---

第9章 安全第一：权限与沙箱

本章目标：建立安全意识，让读者知道”怎么放开能力但不翻车”

章节结构：

• 9.1 为什么Agent更需要最小权限
• 9.2 工具权限：allow/deny/profile策略
• 9.3 执行审批：高风险动作的二次确认
• 9.4 沙箱配置：session/agent/shared模式
• 9.5 凭证管理：Key存在哪里、怎么保护
• 9.6 成本控制：预算上限与频率限制

风格要点：用”锁门”类比权限管理，强调”宁可多确认一次”

---

第五部分：Tools与Skills（读完这部分，它能帮你干活了）

第10章 Tools全景：OpenClaw能拿什么工具

本章目标：让读者了解Tools的能力边界，知道”它能帮我做什么”

章节结构：

• 10.1 Tools vs Skills：零件 vs 说明书
• 10.2 先设护栏：tools.profile / allow / deny / byProvider
• 10.3 工具全景地图：fs/runtime/web/ui/messaging/sessions/nodes
• 10.4 高风险区：exec、process、elevated、审批联动
• 10.5 会话与协作：sessions_*、agents_list、subagents
• 10.6 指令与插件：/model、/think、/exec、plugins
• 10.7 新手三档配置模板（稳健/开发/消息）

风格要点：每个工具组给一个”你能用它做什么”的真实场景

---

第11章 使用现成Skills：从ClawHub安装

本章目标：让读者能搜索、安装、使用现成的Skills

章节结构：

• 11.1 ClawHub是什么：Skill的应用商店
• 11.2 搜索与安装：clawhub search/install/update/sync
• 11.3 Skills加载优先级：workspace / ~/.openclaw / bundled
• 11.4 可用性门控：metadata requires + skills list --eligible
• 11.5 运行期配置：entries.env/apiKey、watch、extraDirs
• 11.6 调用方式：对话触发、/skill、command-dispatch
• 11.7 安全与治理：第三方Skill审阅、版本和回滚

风格要点：用”App Store”类比ClawHub，降低理解门槛

---

第12章 写第一个Skill：日报生成器

本章目标：手把手带读者从零写一个Skill，理解Skill的结构

章节结构：

• 12.1 选题：为什么选择”日报生成”
• 12.2 SKILL.md结构：frontmatter + Use when + Inputs + Steps
• 12.3 编写过程：一步步写出第一个Skill
• 12.4 测试与调试：skills check/info
• 12.5 发布到ClawHub：分享你的作品

风格要点：用”搭积木”类比Skill编写，每一步配代码块

---

第13章 Skill进阶：让它稳定可靠

本章目标：让读者掌握写出”生产级”Skill的技巧

章节结构：

• 13.1 幂等性：重复执行不乱套
• 13.2 错误处理：失败时给明确的下一步
• 13.3 超时与重试：别让一个卡住的调用拖死
• 13.4 限流与降级：保护你的API额度
• 13.5 文档与版本：CHANGELOG的重要性

风格要点：用”做工程”而非”写脚本”的心态来讲

---

第六部分：进阶与排障（读完这部分，你能自己解决问题了）

第14章 排障手册：从现象到根因

本章目标：系统化的排障方法，让读者成为”能自己解决问题”的用户

章节结构：

• 14.1 排障方法论：status → doctor → logs
• 14.2 安装问题：Node版本、权限、网络
• 14.3 模型问题：鉴权、额度、模型不存在
• 14.4 渠道问题：连接、配对、消息不通
• 14.5 Skill问题：依赖、eligible、执行失败

风格要点：用”侦探破案”类比排障，给出”如果X→检查Y→动作Z”的决策树

---

第15章 多Workspace与多Agent

本章目标：满足进阶用户的隔离需求

章节结构：

• 15.1 什么时候需要拆分Workspace
• 15.2 多Agent的配置与路由
• 15.3 Session隔离策略
• 15.4 反模式：过度拆分的问题

风格要点：用”先稳后拆”原则，反对过度工程化

---

第16章 部署与运维：从本地到服务器

本章目标：满足将OpenClaw部署到服务器的需求

章节结构：

• 16.1 本地 vs 云主机：选择依据
• 16.2 远程访问：Tailscale vs SSH隧道
• 16.3 服务守护：systemd/LaunchAgent配置
• 16.4 备份与恢复
• 16.5 升级策略

风格要点：明确”先本地跑稳，再上云”

---

第七部分：附录（速查与索引）

附录A CLI命令速查

按场景分类的命令速查表：安装、配置、频道、技能、诊断

附录B 配置文件完整示例

一份带注释的完整openclaw.json示例

附录C 官方资源索引

GitHub、Docs、Releases、Community的链接与说明

附录D 版本冻结点记录

本书核验的OpenClaw版本与关键变更记录

---

写作检查清单（每章完成前必查）

• 本章开头明确告诉读者”学完这章你能做什么”
• 所有术语首次出现都有解释+例子
• 所有命令经过实测（冻结点版本v2026.2.17）
• 关键步骤有截图位置说明
• 每章有”常见问题”小节
• 有事实核验区块（编辑注，灰色显示）
• 链接使用”文字 + URL”格式，方便纸质书读者