01-AI 工具与智能体/01-OpenClaw - 合集 - Cygnus Tech Blog

第01章 OpenClaw 是什么 —— 自托管个人 AI 助手的终极形态

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

你有没有想过：拥有一个完全属于你自己的 AI 助手，它可以：

在你所有常用的聊天平台（WhatsApp/Telegram/Discord/iMessage）上工作
本地运行，你的数据不会离开你的设备
支持多个 AI 模型，你可以自由切换 Anthropic/OpenAI/Google 等等
内置浏览器自动化，可以帮你自动浏览网页
支持定时任务，定期帮你收集信息
多智能体协作，让多个专家 AI 一起帮你解决复杂问题
开放技能市场，你可以随时安装新技能

这就是 OpenClaw。

OpenClaw 定义

OpenClaw 是一个开源自托管个人 AI 助手网关，它帮你把 AI 能力接入到你日常使用的聊天平台，让 AI 随时随地陪伴你。

第02章核心架构总览 —— Gateway 为什么是中心控制平面

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

上一章我们介绍了 OpenClaw 是什么。本章我们来看整体架构，理解 Gateway 为什么是中心控制平面。

设计目标

OpenClaw 架构设计要解决几个问题：

第03章 Gateway —— 核心网关服务到底做了什么

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

上一章我们说了 Gateway 是中心控制平面。本章我们深入讲解 Gateway 核心服务，看它具体做了哪些事情。

Gateway 定位

Gateway 不是 AI 模型本身，它是胶水层：

第04章多渠道接入 —— 如何支持 25+ 聊天平台

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 最方便的一点就是：你不用换聊天软件，AI 直接出现在你天天都用的聊天软件里。

本章我们讲解 OpenClaw 怎么做到支持 25+ 聊天平台，架构设计是什么样的。

什么是多渠道接入

“多渠道"就是：

第05章 ACP —— 如何对接外部 AI 客户端

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

如果你已经在本机装了 Codex、Claude Code、Gemini CLI、OpenCode 这类外部编码代理，OpenClaw 不需要重造一套运行时。它可以通过 ACP agents 把这些外部 harness 接进自己的会话体系里。

这一章只讲当前源码里的真实能力，不讲已经废弃或不存在的旧接口。

什么是 ACP

ACP 指的是 Agent Client Protocol。在 OpenClaw 里，它的作用很明确：

第06章消息路由 —— 消息如何正确送到对的会话

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 的路由不是“模型自己决定回复到哪里”，而是 Gateway 按确定性规则选定 agent 和 session key。当前源码里，这套逻辑主要围绕 bindings、session key 和线程绑定展开。

路由真正解决的问题

路由层要同时回答两个问题：

第07章安全模型 —— 配对白名单如何保护你

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 跑在你自己服务器上，对外开放吗？谁能访问你的 AI？这就是安全模型要解决的问题。

OpenClaw 默认安全策略：默认拒绝，手动配对允许。本章我们讲解这个设计。

威胁模型

你把 Gateway 暴露在互联网上，可能的威胁：

第08章为什么你需要一个多智能体框架 —— 单智能体的困境

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

你是否有过这样的经历：

用大模型帮你处理一个比较复杂的任务，一开始进展顺利，但是随着任务推进，模型开始"健忘"——前面已经讨论清楚的设计决策，后面又忘了，需要你反复提醒；改完了 A 部分，又把 B 部分改错了；想让它同时处理需求分析、代码编写、测试用例，结果每个部分都写得马马虎虎。

如果你用过 Claude Code 或者其他 AI 编程助手，你一定深有体会。

单智能体的困境

当我们用大模型处理复杂任务时，我们默认都是"单智能体模式"——一个对话窗口，一个模型，从头到尾处理整个任务。这种方式在任务简单的时候工作得很好，但是当任务变得复杂，问题就来了：

第09章 sessions_spawn —— 多智能体协作的核心原语

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 的多智能体协作不是靠“偷偷起一个线程”实现的，而是靠一个明确的会话工具：sessions_spawn。

当前源码里，它的职责很单纯：

在隔离会话里启动一个子智能体运行，并在完成后把结果 announce 回请求方聊天渠道。

它到底生成了什么

普通 sub-agent 的会话键长这样：

第10章协作架构模式 —— 从 Master-Worker 到 Hub-and-Spoke

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

有了 sessions_spawn 这个核心原语，我们就可以构建不同的多智能体协作架构。OpenClaw 并不强制你用某种特定模式，你可以根据任务特点选择最合适的模式。

本文介绍四种常见的协作模式，我们会分析每种模式的优缺点，以及什么时候该用它。

四种常见协作模式

1. Master-Worker 模式

%%{init: {'theme':'base','themeVariables': {'primaryColor':'#f1f5f9','primaryBorderColor':'#0f4c81','primaryTextColor':'#0f172a','secondaryColor':'#f1f5f9','secondaryBorderColor':'#0f4c81','secondaryTextColor':'#0f172a','tertiaryColor':'#fbbf24','tertiaryBorderColor':'#fbbf24','tertiaryTextColor':'#0f172a','background':'#f8fafc','fontFamily':'Inter, system-ui, sans-serif','fontSize':'14px','textColor':'#0f172a','lineColor':'#334155','edgeLabelBackground':'#ffffff','actorBorderColor':'#0f4c81','actorTextColor':'#0f172a','actorFill':'#f1f5f9'}}}%%
graph TD
 M[Master<br/>Coordinator] --> W1[Worker 1]
 M --> W2[Worker 2]
 M --> W3[Worker 3]
 W1 --> M
 W2 --> M
 W3 --> M

结构：一个协调者（Master）把任务分解给多个工人（Workers），工人完成后把结果返回给协调者，协调者汇总结果。

第11章隔离设计 —— 为什么每个子智能体需要独立会话

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

很多人第一次接触 sessions_spawn 会有疑问：不就是让另一个 AI 干活吗，为什么非要搞个独立会话？直接在当前上下文调用不行吗？

答案很简单：隔离带来健壮性。没有隔离，多智能体协作很容易变成一团乱麻。

什么是隔离

OpenClaw 中，每次 sessions_spawn 都会创建一个全新的独立会话：

第12章嵌套协作 —— 如何实现 Orchestrator-Worker 模式

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

前面我们说到，OpenClaw 默认 maxSpawnDepth: 1，也就是主智能体可以 spawn 子智能体，但子智能体不能再 spawn 子子智能体。

但是如果你打开 maxSpawnDepth: 2，就可以支持两层嵌套：

Depth 0: Main Hub (orchestrator)
 ↳ spawn Depth 1: Team Coordinator
 ↳ spawn Depth 2: Worker

这就是 Orchestrator-Worker 模式（或者叫两层编排模式）。什么时候需要这个？本文来讲清楚。

什么场景需要嵌套

你有一个比较大的任务，比如：调研 10 篇论文，总结它们的核心贡献。

第13章实践案例 —— 从零构建一个代码评审团队

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

前面五章我们讲完了理论：为什么需要多智能体、核心原语 sessions_spawn、协作架构模式、隔离设计、嵌套协作。

本章我们来做一个完整的实践案例：用 OpenClaw 构建一个自动化代码评审团队。看完这个案例，你就可以照着做，构建自己的多智能体协作系统。

需求分析

我们想要一个这样的代码评审系统：

第14章 platforms —— 全平台安装部署指南

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 设计为分布式架构：Gateway 网关跑在你的服务器或某台机器上，然后各个端侧设备（Mac/iOS/Android）作为"节点"连接上来，提供设备本地能力。本章我们讲解各个平台的安装、部署和使用。

架构角色说明

在开始之前，先理清两个概念：

第15章 providers —— 各大模型提供者配置大全

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 支持几乎所有主流大语言模型提供者，从云端 API 到本地部署都可以。本章我们讲解几个最常用的模型提供者的配置方法。

什么是模型提供者

模型提供者就是提供 AI 模型推理服务的地方：

第16章 plugins —— 插件系统开发指南

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 设计了强大的插件系统，让你可以扩展核心功能，添加新的聊天渠道、模型提供者、工具、技能等。本章我们讲解插件系统架构，以及如何开发自己的插件。

什么是插件

插件就是一个独立的代码模块，扩展 OpenClaw 核心功能，不用改核心代码就能添加新能力：

第17章 refactor —— OpenClaw 重构原则与工作流

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 持续演进，会定期进行大规模重构来保持代码健康。本章我们讲解 OpenClaw 的重构原则、正在进行的主要重构项目，以及重构工作流。

重构原则

OpenClaw 重构遵循这些核心原则：

第18章 reference —— 完整配置、模板、CLI 命令参考

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

这一章只保留和当前工程一致的参考信息：配置文件位置、常见顶层结构、工作区模板文件，以及最常用的 CLI 命令族。

配置文件位置

当前 OpenClaw 使用的主配置文件是：

第19章 skills —— 技能系统核心概念与开发指南

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

当前 OpenClaw 的 Skills 采用 AgentSkills 风格的目录 + SKILL.md 方案。

这一章按当前工程里的真实结构来讲。

什么是 Skill

在当前 OpenClaw 里，一个 Skill 本质上是：

第20章 ClawHub —— 技能市场如何分享和获取技能

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

ClawHub 在当前 OpenClaw 里不是“一个 GitHub 索引仓库的别名”，而是官方 Skills 注册中心和对应的 CLI 工作流。

如果你要搜索、安装、更新、发布 Skills，当前工程的正确入口是 clawhub。

网站：

https://clawhub.com

ClawHub 是什么

官方文档对它的定位很明确：

第21章 Canvas A2UI —— 实时可视化协作 workspace

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

Canvas 是 OpenClaw 的AI+人实时协作画布，让你和 AI 在同一个可视化工作空间一起工作。本章我们介绍 Canvas A2UI（AI to User Interface）的设计理念和使用方法。

什么是 Canvas A2UI

Canvas = 无限画布 + 实时块渲染 + AI 协作：

第22章语音唤醒 (Voice Wake) —— 语音交互体验

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

语音唤醒是 OpenClaw 的 always-ready 交互模式，设备一直监听，你说唤醒词就直接响应，不用手动点按钮。本章介绍语音唤醒的配置、工作原理和最佳实践。

什么是语音唤醒

语音唤醒 = 离线监听 + 关键词触发 + 语音对话：

第23章 WebChat —— Gateway WebSocket 聊天界面

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

当前官方文档里，WebChat 的定位是：

它是一个直接连 Gateway WebSocket 的聊天 UI，不是独立的一套 Web 服务器产品。

当前 WebChat 是什么

官方文档给出的定义是：

第24章工具系统 (Tools) —— OpenClaw 工具调用框架设计

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 的工具体系是按内置工具名、工具组和策略配置来组织的。

当前工具系统的几个核心点

1. 工具是一级能力

当前官方文档明确列出的内置重点包括：

第25章内置浏览器 —— 网页抓取和交互

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

当前 OpenClaw 的浏览器能力由 Browser (openclaw-managed)、chrome extension relay，以及 agent 侧 browser 工具 / openclaw browser CLI 组成，核心配置块在：

browser

不是插件配置块。

当前浏览器能力是什么

按当前官方文档，可以概括为：

第26章 Cron 自动化 —— 定时任务自动化

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 的 cron 是一个Gateway 内置调度器，专门用于处理定时任务。与传统的 crontab 或需要外部依赖的方案不同，OpenClaw 的 cron 直接运行在 Gateway 内部，支持多种执行模式，并且任务会自动持久化。

推荐操作入口是 openclaw cron ... 命令，任务持久化在状态目录里，不需要手工维护复杂的配置文件。

Cron 是如何工作的

flowchart TD
 A[创建 Cron 任务<br/>openclaw cron add] --> B[任务持久化<br/>~/.openclaw/cron/jobs.json]
 B --> C{等待触发时间}
 C -->|到时| D{执行模式}
 D -->|main| E[发送事件到主会话<br/>systemEvent]
 D -->|isolated| F[启动独立会话<br/>agentTurn]
 E --> G[任务执行]
 F --> G
 G --> H{投递方式}
 H -->|announce| I[发送到聊天渠道]
 H -->|webhook| J[发送到外部 URL]
 H -->|none| K[静默结束]
 I --> L{是否删除}
 J --> L
 K --> L
 L -->|deleteAfterRun=true| M[删除任务]
 L -->|false| N[保留任务继续调度]

官方文档的定义很明确：

第27章 Onboarding —— 新手引导流程设计

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

Onboarding 是 OpenClaw 的新手安装配置引导流程，帮助你从零一键完成配置，不用手改 JSON。本章介绍 Onboarding 工作流程、交互界面和最佳实践。

什么是 Onboarding

Onboarding = 交互式命令行配置向导：

第28章 blogwatcher —— 博客与 RSS 更新监控

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

你关注了多少个技术博客？10 个？20 个？还是更多？

每天打开浏览器，逐个访问这些网站，看看有没有新文章发布，这听起来是不是很枯燥？更糟糕的是，你可能会错过那些真正重要的更新——因为谁有时间和耐心每天检查几十个网站呢？

RSS 订阅确实是个解决方案，但传统的 RSS 阅读器往往功能有限，要么不支持智能过滤，要么无法与你的工作流无缝集成。你想要的是一个能够：

自动监控你关注的博客和 RSS feeds
实时检测新文章发布
智能管理阅读状态
与你的日常工作环境无缝衔接

这样的工具存在吗？

OpenClaw 内置的 blogwatcher skill 就是为此而生的。

blogwatcher 是什么

当前内置 blogwatcher skill 的描述很直接：

第29章 gh-issues —— GitHub Issues 自动修复编排

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

想象一下这样的场景：你的开源项目仓库里堆积了 50+ 个待处理的 bug 报告，每个都需要你手动分析、定位问题、编写修复代码、创建 PR、等待 review、再根据反馈修改……这听起来是不是很让人头疼？

更糟糕的是，其中很多问题其实是重复的、简单的，或者可以通过自动化方式解决的。你把大量时间花在这些重复性工作上，真正需要你深度思考的核心功能开发反而被挤占了。

如果有一个工具能够：

自动拉取 GitHub issues
智能分析每个问题
派发专门的子代理编写修复代码
自动创建 PR 并提交
持续监控 review comments 并处理反馈

你会不会觉得这简直是开发者的福音？

好消息是，OpenClaw 内置的 gh-issues skill 就能帮你实现这一切。

`gh-issues` 是什么

当前内置 gh-issues 的描述是：

第30章 coding-agent —— 调用外部编码代理

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

面对一个复杂的新功能开发任务，你是否有过这样的经历：

需要深入理解整个代码库的结构和设计模式
要在多个文件之间来回切换，理解上下文关系
编写代码时需要不断查阅文档和参考实现
代码写完后还要进行全面的测试和 review

这些工作如果完全靠人工完成，不仅耗时耗力，还容易出错。你可能会想：如果有一个专业的编码助手能够帮我处理这些复杂的编码任务，那该多好？

现在市面上确实有很多优秀的编码工具——Codex、Claude Code、Pi、OpenCode 等等。但问题是，它们各自独立运行，无法与你的工作流无缝集成。你需要在不同的工具之间切换，打断你的开发节奏。

如果能够把这些强大的编码代理统一纳入你的工作流，让它们在你需要的时候自动介入，处理那些复杂的编码任务，那会是一种怎样的体验？

OpenClaw 内置的 coding-agent skill 就能帮你实现这一点。

`coding-agent` 是什么

当前 coding-agent skill 的描述非常明确：

第31章模型故障转移 (Model Failover) —— 如何提高可用性

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

模型 API 不是 100% 可用，会有超时、限流、宕机。OpenClaw 设计了模型故障转移机制，主模型不可用时自动切备用模型，保证你的任务能继续跑。本章讲解故障转移配置和最佳实践。

什么是模型故障转移

故障转移 = 主模型挂了自动切下一个：

第32章调试技巧 —— 如何排查 OpenClaw 问题

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 出问题了怎么快速定位？本章汇总常用调试技巧，帮你快速找到问题解决问题。

第一步：运行健康检查

不管什么问题，先跑这个：

第33章成本优化 —— 如何用模型分级降低总成本

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 原生支持多模型，你可以用模型分级把成本降下来，同时保持体验差不多。本章分享实战成本优化技巧。

核心思想：模型分级，按任务分配模型

不是什么任务都用最强最贵的模型：

第34章部署运维 —— OpenClaw 网关生产环境最佳实践

ruohuyang@163.com (Cygnus Yang) — Sat, 23 May 2026 00:00:00 +0800

OpenClaw 设计就是为了生产环境长期运行，本章汇总生产环境部署运维的最佳实践，帮你跑稳跑顺。

部署架构选择

选项 1：单机部署（推荐个人/小团队）

你的服务器 → OpenClaw Gateway 直接跑 → 反向代理 Nginx → 域名 HTTPS

简单，一台机器搞定
数据都在你自己机器
维护方便，升级简单

适合：个人使用、小团队、不需要高可用。

01-AI 工具与智能体/01-OpenClaw - 合集 - Cygnus Tech Blog

第01章 OpenClaw 是什么 —— 自托管个人 AI 助手的终极形态

OpenClaw 定义

第02章 核心架构总览 —— Gateway 为什么是中心控制平面

设计目标

第03章 Gateway —— 核心网关服务到底做了什么

Gateway 定位

第04章 多渠道接入 —— 如何支持 25+ 聊天平台

什么是多渠道接入

第05章 ACP —— 如何对接外部 AI 客户端

什么是 ACP

第06章 消息路由 —— 消息如何正确送到对的会话

路由真正解决的问题

第07章 安全模型 —— 配对白名单如何保护你

威胁模型

第08章 为什么你需要一个多智能体框架 —— 单智能体的困境

单智能体的困境

第09章 sessions_spawn —— 多智能体协作的核心原语

它到底生成了什么

第10章 协作架构模式 —— 从 Master-Worker 到 Hub-and-Spoke

四种常见协作模式

1. Master-Worker 模式

第11章 隔离设计 —— 为什么每个子智能体需要独立会话

什么是隔离

第12章 嵌套协作 —— 如何实现 Orchestrator-Worker 模式

什么场景需要嵌套

第13章 实践案例 —— 从零构建一个代码评审团队

需求分析

第14章 platforms —— 全平台安装部署指南

架构角色说明

第15章 providers —— 各大模型提供者配置大全

什么是模型提供者

第16章 plugins —— 插件系统开发指南

什么是插件

第17章 refactor —— OpenClaw 重构原则与工作流

重构原则

第18章 reference —— 完整配置、模板、CLI 命令参考

配置文件位置

第19章 skills —— 技能系统核心概念与开发指南

什么是 Skill

第20章 ClawHub —— 技能市场如何分享和获取技能

ClawHub 是什么

第21章 Canvas A2UI —— 实时可视化协作 workspace

什么是 Canvas A2UI

第22章 语音唤醒 (Voice Wake) —— 语音交互体验

什么是语音唤醒

第23章 WebChat —— Gateway WebSocket 聊天界面

当前 WebChat 是什么

第24章 工具系统 (Tools) —— OpenClaw 工具调用框架设计

当前工具系统的几个核心点

1. 工具是一级能力

第25章 内置浏览器 —— 网页抓取和交互

当前浏览器能力是什么

第26章 Cron 自动化 —— 定时任务自动化

Cron 是如何工作的

第27章 Onboarding —— 新手引导流程设计

什么是 Onboarding

第28章 blogwatcher —— 博客与 RSS 更新监控

blogwatcher 是什么

第29章 gh-issues —— GitHub Issues 自动修复编排

gh-issues 是什么

第30章 coding-agent —— 调用外部编码代理

coding-agent 是什么

第31章 模型故障转移 (Model Failover) —— 如何提高可用性

什么是模型故障转移

第32章 调试技巧 —— 如何排查 OpenClaw 问题

第一步：运行健康检查

第33章 成本优化 —— 如何用模型分级降低总成本

核心思想：模型分级，按任务分配模型

第34章 部署运维 —— OpenClaw 网关生产环境最佳实践

部署架构选择

选项 1：单机部署（推荐个人/小团队）

第02章核心架构总览 —— Gateway 为什么是中心控制平面

第04章多渠道接入 —— 如何支持 25+ 聊天平台

第06章消息路由 —— 消息如何正确送到对的会话

第07章安全模型 —— 配对白名单如何保护你

第08章为什么你需要一个多智能体框架 —— 单智能体的困境

第10章协作架构模式 —— 从 Master-Worker 到 Hub-and-Spoke

第11章隔离设计 —— 为什么每个子智能体需要独立会话

第12章嵌套协作 —— 如何实现 Orchestrator-Worker 模式

第13章实践案例 —— 从零构建一个代码评审团队

第22章语音唤醒 (Voice Wake) —— 语音交互体验

第24章工具系统 (Tools) —— OpenClaw 工具调用框架设计

第25章内置浏览器 —— 网页抓取和交互

`gh-issues` 是什么

`coding-agent` 是什么

第31章模型故障转移 (Model Failover) —— 如何提高可用性

第32章调试技巧 —— 如何排查 OpenClaw 问题

第33章成本优化 —— 如何用模型分级降低总成本

第34章部署运维 —— OpenClaw 网关生产环境最佳实践