OpenClaw 完全指南：从原理到生产实战

Ch01

OpenClaw 是什么：从 Clawdbot 到爆火的开源 AI Agent 平台

OpenClaw 的诞生背景、改名历程、MIT 许可证定位、核心理念（本地优先/多平台/可扩展）、与同类工具的本质区别、247k GitHub Stars 背后的产品逻辑

Ch02

15分钟搭建第一个 Agent：安装、配置、跑通第一次对话

三种安装方式（curl/npm/源码），系统要求，onboard 流程，openclaw.json 最小化配置，连接第一个 LLM，发送第一条消息，常见报错排查

Ch03

核心概念全景：Gateway / Pi / Skills / Plugin / Memory 的关系图

五大核心组件的职责边界、相互依赖关系、数据流向全景图，以及 Channel/Session/Binding/Tool 等关键术语的准确定义

Ch04

与 LangChain / AutoGen / CrewAI 的本质区别：配置驱动 vs 代码驱动

六维度对比矩阵（定位/语言/安装/抽象层次/集成数量/记忆系统），配置驱动范式的优势与代价，选型决策树，适用团队画像

Ch05

五层架构拆解：一条消息从到达到执行的完整链路

Input Sources → Integration Gateway → Agent Core → Action Layer → External Systems 五层的职责、技术实现与关键设计决策，附完整时序图

Ch06

Gateway 控制平面：WebSocket 协议、三步握手与 Session 解析算法

Gateway 为何绑定 localhost、WebSocket 消息三种格式（req/res/event）、认证握手序列、dmPolicy 四种模式、Session Key 生成算法、Single-writer 设计原则

Ch07

Command Queue：Lane-aware FIFO 与四种队列模式的设计取舍

四个 Lane（Global/Session/Sub-agent/Cron）的并发设置与隔离原因，collect/steer/followup/steer-backlog 四种模式的触发场景与行为差异，防止状态竞争的关键设计

Ch08

Pi 框架：极简主义 Agent 执行引擎的设计哲学与四大核心包

为什么只有 4 个基础工具、System Prompt 控制在 1000 tokens 以下的理由、pi-ai/pi-agent-core/pi-coding-agent/pi-tui 四包职责、嵌入式而非 subprocess 的架构决策

Ch09

Pi Agent 执行循环：状态机、11个生命周期事件与7层工具管道

createAgentSession 完整参数解析，agent_start→turn→message→tool→agent_end 状态机，循环终止五个条件，7层工具注入过滤管道（基础工具→沙箱替换→扩展工具→渠道工具→策略过滤→Schema规范化→AbortSignal包装）

Ch10

消息路由：Bindings 规则引擎与八级优先级匹配算法

Peer match→Parent peer→Guild+角色→Guild ID→Team ID→Account ID→Channel→默认回退 八级路由优先级详解，多 Agent 分流配置模式，Session Freshness 评估机制

Ch11

12+ Provider 全接入：Anthropic / OpenAI / Google / Bedrock / 本地模型

12个官方 Provider 的认证方式、模型 ID 格式（provider/model-id）、Anthropic Claude 系列、OpenAI GPT 系列、Google Gemini 系列、AWS Bedrock 配置、DeepSeek/MiniMax/xAI 等接入实战

Ch12

模型配置深度：Key Rotation、Failover 机制与推理深度控制

多 Key 优先级轮换策略、429/quota 自动重试、FailoverError 触发模型切换、Profile 冷却追踪、/think adaptive/high/off 推理控制、按渠道绑定不同模型

Ch13

本地模型部署：Ollama / LM Studio / vLLM 完整接入实战

兼容 OpenAI API 端点的配置方法、Ollama 拉取与运行、LM Studio 服务暴露、vLLM/SGLang 高性能推理、本地模型的隐私优势与性能取舍、推荐模型选型

Ch14

内置工具全解：16个核心工具的能力边界与适用场景

read/write/edit/exec/bash/process/browser/web_search/message/cron/memory_search/memory_get/sessions_spawn/canvas/node controls 全解，每个工具的输入输出格式与适用场景

Ch15

工具策略：Allow/Deny 规则、沙箱三级配置与 elevated 标志

全局 deny > 全局 allow 的优先级规则、per-agent 例外配置、沙箱 off/non-main/all 三级与 session/agent/shared scope、Docker/SSH/OpenShell 后端选择、elevated 绕过逻辑

Ch16

ACP 协议：调用 Claude Code / Codex / Gemini CLI 作为外部 Harness

ACP 架构定位（OpenClaw 编排层 vs Harness 运行时自治），10种支持的 Harness，spawn/status/close 操作，Interactive vs Background 交付模式，复杂项目准确率提升 25-35% 的原理

Ch17

Skills 系统原理：SKILL.md 格式、懒加载机制与 description 触发逻辑

Skills 是教科书不是代码、SKILL.md 完整字段规范、metadata.openclaw 全字段解析、懒加载（仅注入元数据按需加载全文）原理、description 是模型触发决策的核心、五级加载优先级

Ch18

从零编写 Skills：5种模式完整示例与最佳实践

工具型/信息型/自动化型/command-dispatch型/TDD专业型 5种模式完整 SKILL.md 示例，Progressive Disclosure 设计，{baseDir} 引用技巧，Degree of Freedom 匹配原则，Token 成本优化

Ch19

ClawHub 生态：13,000+ Skills 分类、Top 10 精选与安装指南

ClawHub 十大分类与数量统计、最热门 10 个 Skills（安装量排名）、awesome-openclaw-skills 精选方法论、clawhub install 与手动安装流程、Skills 发布流程

Ch20

高级 Skills 技巧：OS 过滤、依赖门控、command-dispatch 与 Token 控制

requires.bins/env/config 依赖声明实战、os 字段 darwin/linux/win32 过滤、always 跳过所有 gate、command-dispatch 实现零推理成本调用、disable-model-invocation 隐藏 Skill、install 自动安装脚本

Ch21

Skills 安全：ClawHavoc 6种注入技术复盘与完整 SKILL.md 审计清单

ClawHavoc 事件时间线、staged download/Python reverse shell/Base64社工/ClickFix/休眠载荷/动态拉取 6种攻击手法、AMOS 载荷能力、安装前五步审计流程、安全 Skill 特征清单

Ch22

Plugin 架构原理：8步加载管道与单向依赖设计原则

Discovery→Manifest Reading→Safety Gates→Config Normalization→Enablement Decision→Module Loading→Hook Invocation→Registry Population 八步详解，Manifest 是控制面 source of truth，单向加载原则防止全局状态污染

Ch23

Plugin API 全解：45个 Hook 的7个阶段调用顺序与穿透规则

配置物化→模型解析→认证解析→模型准备→推理配置→流式传输→运行时 7个阶段的 45个 hook 调用时机，穿透规则（先匹配 provider 再穿透其他 plugin），registerProvider/Channel/Tool/HttpRoute 完整签名

Ch24

编写第一个 Plugin：Channel / Tool / Provider 三种类型实战

Plugin 目录结构与 Manifest 格式，Channel Plugin（新增消息平台），Tool Plugin（暴露新工具），Provider Plugin（接入新 LLM），HTTP Route 安全分级（plugin vs gateway auth），jiti 热加载开发流程

Ch25

Skills vs Plugin 决策框架：能力边界对比与协作模式

8维度对比表（运行层/实现形式/加载时机/Token成本/能力上限/迭代速度）、Plugin 能做但 Skill 做不到的场景、Skill 能做但 Plugin 做不到的场景、协作模式（Plugin 提供管道 + Skill 教使用方法）

Ch26

Memory 四层架构：Session Context → Daily Logs → MEMORY.md → Vector Index

四层的存储位置、加载时机、适用信息类型、文件即数据库的设计哲学（Markdown 是 source of truth，SQLite 是加速层可重建）、Memory 与 Context Window 的关系

Ch27

Compaction 算法：触发公式、Pre-flush 机制与长会话信息保全

触发公式（currentTokens >= contextWindow - reserveFloor - softThreshold），Pre-compaction Memory Flush 静默 agentic turn 原理，memoryFlushCompactionCount 防重复机制，Compaction vs Pruning 区别，Dreaming 后台整合进程

Ch28

向量检索实现：SQLite + BM25 混合检索、0.7/0.3权重融合与 Embedding 降级链

FTS5 虚表关键词检索 + 向量余弦相似度检索并行，Union 而非 Intersection 策略，candidateMultiplier:4 过度获取，Graceful Degradation（任意后端失败不影响另一个），Embedding 四级降级链（本地GGUF→OpenAI→Gemini→纯BM25）

Ch29

Workspace 文件体系全解：AGENTS.md / SOUL.md / USER.md / HEARTBEAT.md 的作用与写法

9个标准 Workspace 文件的加载时机与用途、AGENTS.md（操作指令/SOP）vs SOUL.md（人格/价值观）的核心区别、USER.md 用户画像、HEARTBEAT.md 定期清单、Bootstrap 机制与字符限制

Ch30

安全模型七层防御：从 Gateway 绑定到出站消息门控的完整纵深

Gateway 认证→设备配对→Channel 白名单→工具策略→执行审批→Docker 沙箱→出站门控 七层防御的实现原理与配置方法，各层能防什么不能防什么

Ch31

ClawBleed CVE-2026-25253：Token 反射到 RCE 的完整攻击链分析

两个独立漏洞（Token 反射 + gatewayUrl 注入）组合成 CVSS 9.8 的四步攻击链，40,214 个暴露实例统计，ClawJacked localhost 绑定绕过原理，修复方案与应急响应步骤，同期披露的 4 个关联 CVE

Ch32

ClawHavoc 供应链攻击：6种注入技术、AMOS 载荷与 AI Agent 供应链安全盲区

时间线复盘，单用户 354 个恶意包自动化上传，staged download/reverse shell/Base64/ClickFix/休眠激活/动态拉取 6种技术，AMOS 完整能力（keychain/浏览器/加密钱包/SSH），传统安全工具对 prompt injection 的失效原因

Ch33

生产安全加固：最小权限配置、Skills 审计流程与 security audit 命令

Gateway 安全硬化配置（loopback绑定/强Token/sandbox all/tools allowlist），Skills 安装前五步审计流程，红旗信号清单，openclaw security audit 扫描项，Tailscale 远程访问替代公网暴露

Ch34

Multi-Agent 路由：Bindings 配置模式与多账号/多渠道分流实战

Agent 完整隔离原理（独立 Workspace/状态目录/Session Store），按渠道分流配置（WhatsApp→fast/Telegram→opus），按账号分流（个人号→home/商务号→work），Binding 匹配失败回退逻辑

Ch35

Sub-agents：非阻塞委托执行、跨 Agent 记忆搜索与结构化通信

sessions_spawn 工具的非阻塞返回机制（立即返回 run ID），Sub-agent 的隔离 Session 与受限工具访问，结果自动公告，跨 Agent 记忆搜索配置（memorySearch.qmd.extraCollections），与 ACP Harness 的区别

Ch36

Nodes 架构：物理设备接入原理（macOS / iOS / Android / 树莓派）

Node 以 role:node WebSocket 连接 Gateway、Capability 声明机制、设备配对流程（list/approve）、各平台能力矩阵（macOS/iOS/Android/Headless）、摄像头/屏幕录制/位置/通话记录/SMS 等接口

Ch37

边缘计算实战：树莓派 24/7 Always-On Agent Node 完整搭建

树莓派配置要求、openclaw node run 远程连接命令、systemd 开机自启、Gateway 云端/Pi 本地分工（云端推理+本地执行），传感器数据采集、摄像头自动上报、低功耗 always-on 最佳实践

Ch38

Control UI 深度：配置编辑、实时日志、审批管理与 Dream Diary

Vite+Lit 技术栈、WebRTC 语音 Talk mode、Tool 调用流式卡片、双模式配置编辑（表单/原始JSON）、Session 覆盖、Cron 追踪、Node 能力检查、日志实时拖尾与导出、Dream Diary 记忆内省

Ch39

生产部署：AWS ARM64 + systemd + Tailscale 参考架构

t4g.xlarge ARM64 Graviton 选型理由、Ubuntu 系统配置、systemd 服务单元文件、环境变量安全注入、Tailscale Serve 替代公网暴露、备份策略（~/.openclaw git 化）、多实例部署隔离

Ch40

性能调优：Token 成本控制、Context 预算管理与并发 Lane 配置

Skills 懒加载减少每次 Token 消耗、command-dispatch 实现零推理成本调用、Compaction 触发阈值调整、Per-provider 模型成本矩阵、Lane 并发数调优、API Key Rotation 平衡 quota 用量

Ch41

监控与可观测性：结构化日志、健康检查与告警配置

openclaw.json logging 配置（级别/输出），Gateway 健康检查端点，日志结构字段解析，关键指标（Session 成功率/工具错误率/Compaction 频率），与 Prometheus/Grafana 集成思路，告警规则设计

Ch42

10个真实案例：个人助手 / 代码审查 / SEO流水线 / IoT 边缘自动化等

每日简报、邮件管理、PR 审查助手、多文件重构（ACP+Claude Code）、竞品情报监控、客户入驻自动化、语音驱动 DevOps、SEO 内容流水线（节省50小时/周）、树莓派摄像头守卫、Slack 事件响应机器人

Ch43

OpenClaw 生态走向：基金会模式、ACP 标准化与开源社区现状

Peter Steinberger 加入 OpenAI 后的项目治理变化、基金会管理模式、ACP 协议标准化进展（agentclientprotocol.com）、主要赞助商（OpenAI/GitHub/NVIDIA/Vercel）、社区贡献节奏与版本发布策略