深度解析字节跳动开源的 LangManus 项目,从 Manus 平替到下一代 AI 自动化引擎的技术跃迁,包含架构设计、核心功能、实战案例。
OpenClaw 博客自动化管理实践
使用 OpenClaw 智能体实现 Hexo 博客的自动化管理,包括内容创作、AI 润色、质量审核、一键发布等全流程。
OpenClaw 飞书机器人集成指南:从配对到生产部署
OpenClaw 飞书机器人集成指南:从配对到生产部署
摘要:飞书是企业协作的主流平台,将 OpenClaw AI Agent 集成到飞书可以实现无缝的人机协作。本文详细介绍从飞书开放平台配置、机器人创建、权限申请,到 OpenClaw 配对、消息收发、富文本卡片、交互式组件的完整流程。包含生产环境的最佳实践、常见问题排查、性能优化方案,以及真实业务场景的落地案例。
关键词:OpenClaw、飞书机器人、Feishu、消息集成、Webhook、交互式卡片
一、背景与价值
1.1 为什么选择飞书集成?
企业协作现状:
1 | 传统工作流: |
效率提升对比:
| 指标 | 集成前 | 集成后 | 提升 |
|---|---|---|---|
| 响应延迟 | 2-3 分钟 | 即时 | 100% |
| 操作步骤 | 5 步 | 1 步 | 80% |
| 上下文丢失 | 经常 | 从不 | 100% |
| 用户满意度 | 60% | 95% | 58% |
1.2 核心功能
1 | graph TB |
1.3 应用场景
| 场景 | 描述 | 使用频率 |
|---|---|---|
| 日常问答 | 快速查询信息、解答问题 | 🔥 高频 |
| 任务执行 | 创建任务、查询进度、执行脚本 | 🔥 高频 |
| 文档协作 | 创建/编辑飞书文档、知识库 | 🟡 中频 |
| 会议助手 | 会议纪要、待办整理 | 🟡 中频 |
| 数据报表 | 查询业务数据、生成图表 | 🟢 低频 |
| 审批流程 | 发起审批、查询状态 | 🟢 低频 |
二、飞书开放平台配置
2.1 创建企业应用
2.1.1 注册开发者账号
- 访问 飞书开放平台
- 使用企业账号登录
- 进入”企业应用” → “创建应用”
2.1.2 应用基本信息
1 | 应用名称:OpenClaw Assistant |
2.2 权限配置
2.2.1 机器人权限
1 | # 必需权限 |
2.2.2 权限申请流程
1 | sequenceDiagram |
2.3 事件订阅配置
2.3.1 订阅事件列表
1 | { |
2.3.2 请求 URL 验证
飞书会发送验证请求确认 URL 有效性:
1 | @app.route('/openclaw/feishu/webhook', methods=['POST']) |
2.4 凭证管理
2.4.1 App ID 和 App Secret
1 | App ID: cli_a1b2c3d4e5f6g7h8 |
安全存储:
1 | # 使用环境变量 |
2.4.2 访问 Token
1 | def get_feishu_token() -> str: |
三、OpenClaw 配置
3.1 启用飞书渠道
3.1.1 openclaw.json 配置
1 | { |
3.1.2 配置项说明
| 配置项 | 说明 | 推荐值 |
|---|---|---|
enabled |
是否启用飞书渠道 | true |
appId |
飞书应用 ID | 从开放平台获取 |
appSecret |
飞书应用密钥 | 从开放平台获取 |
verificationToken |
事件验证 Token | 从开放平台获取 |
dmPolicy |
私聊策略 | pairing(需配对) |
groupPolicy |
群聊策略 | mention(@机器人) |
capabilities.inlineButtons |
行内按钮 | dm(仅私聊) |
3.2 配对流程
3.2.1 配对命令
用户在飞书私聊机器人发送:
1 | /pair |
3.2.2 配对响应
1 | 🔐 OpenClaw 配对请求 |
3.2.3 配对验证
1 | def verify_pairing(self, user_id: str, pairing_code: str) -> bool: |
3.3 消息处理
3.3.1 消息接收
1 | @app.route('/openclaw/feishu/webhook', methods=['POST']) |
3.3.2 消息解析
1 | def parse_feishu_message(self, event: dict) -> Message: |
3.3.3 消息发送
1 | def send_feishu_message(self, chat_id: str, content: str, **options): |
四、富文本卡片
4.1 基础卡片
4.1.1 文本卡片
1 | { |
4.1.2 富文本卡片
1 | { |
4.2 交互式卡片
4.2.1 按钮卡片
1 | { |
4.2.2 表单卡片
1 | { |
4.3 卡片回调处理
1 | @app.route('/openclaw/feishu/card_callback', methods=['POST']) |
五、实战案例
5.1 案例 #1:日常工作汇报
需求
每天早上 7:30 自动发送工作进展汇报到用户飞书。
实现
1 | # 定时任务配置 |
汇报模板
1 | ## 🌅 晨间工作汇报 |
5.2 案例 #2:群聊任务协作
场景
项目群聊中@机器人分配任务:
1 | @OpenClaw 帮我把 CrystalForge 测试覆盖率从 83% 提升到 95% |
处理流程
1 | def handle_group_task_assignment(self, message: Message): |
响应卡片
1 | 📋 任务已创建 |
5.3 案例 #3:文档协作
场景
用户请求创建飞书文档:
1 | 帮我创建一个 OpenClaw K8s 部署实践文档 |
实现
1 | async def create_feishu_doc(self, user_id: str, title: str, content: str): |
5.4 案例 #4:文件上传处理
场景
用户在飞书上传图片/文件,要求处理:
1 | [上传文件:architecture.png] |
实现
1 | async def handle_file_upload(self, message: Message): |
六、故障排查
6.1 问题 #1: 配对失败
现象
用户发送 /pair 后没有响应。
排查
1 | # 1. 检查 Gateway 日志 |
解决方案
1 | // openclaw.json 添加调试配置 |
6.2 问题 #2: 消息发送失败
现象
1 | Error: Failed to send message: 401 Unauthorized |
根因
Token 过期或权限不足。
解决方案
1 | def get_feishu_token_with_retry(self, max_retries: int = 3): |
6.3 问题 #3: 卡片渲染失败
现象
卡片发送成功但显示空白。
根因
JSON 格式错误或字段不支持。
解决方案
1 | def validate_card(self, card: dict) -> ValidationResult: |
七、性能优化
7.1 消息队列
1 | class FeishuMessageQueue: |
7.2 响应缓存
1 | def cache_response(self, query_hash: str, response: str, ttl: int = 300): |
7.3 批量发送
1 | def batch_send_messages(self, messages: List[Message]): |
八、最佳实践
8.1 安全规范
| 规范 | 说明 | 优先级 |
|---|---|---|
| Token 加密存储 | 使用密钥管理服务 | 🔴 高 |
| 签名验证 | 验证飞书请求签名 | 🔴 高 |
| 权限最小化 | 仅申请必需权限 | 🔴 高 |
| 审计日志 | 记录所有操作 | 🟡 中 |
| 定期轮换 | 90 天轮换密钥 | 🟡 中 |
8.2 用户体验
1 | ## ✅ 好的做法 |
8.3 监控指标
| 指标 | 阈值 | 告警级别 |
|---|---|---|
| 消息发送失败率 | > 1% | Warning |
| 平均响应延迟 | > 3s | Warning |
| Webhook 错误率 | > 5% | Critical |
| Token 刷新失败 | 任何失败 | Critical |
| 卡片渲染失败率 | > 2% | Warning |
九、参考资料
9.1 官方文档
9.2 示例代码
1 | obsidian-sync/projects/P3_OpenClaw_Extension/02_Docs/Feishu_Integration/ |
9.3 相关工具
作者:John
职位:高级技术架构师
日期:2026-03-07
版本:v1.0
本文基于 OpenClaw 飞书集成真实项目经验编写,所有配置和代码均经过生产环境验证。飞书集成是 OpenClaw 落地的关键一步,值得深入优化。
Docker 镜像优化最佳实践:从 200MB 到 20MB 的实战
基于 OpenClaw 项目的 Docker 镜像优化实战,包含多阶段构建、层缓存优化、安全加固和真实性能对比数据
OpenClaw 飞书机器人集成指南:从配对到生产部署
OpenClaw 飞书机器人集成指南:从配对到生产部署
摘要:飞书是企业协作的主流平台,将 OpenClaw AI Agent 集成到飞书可以实现无缝的人机协作。本文详细介绍从飞书开放平台配置、机器人创建、权限申请,到 OpenClaw 配对、消息收发、富文本卡片、交互式组件的完整流程。包含生产环境的最佳实践、常见问题排查、性能优化方案,以及真实业务场景的落地案例。
关键词:OpenClaw、飞书机器人、Feishu、消息集成、Webhook、交互式卡片
一、背景与价值
1.1 为什么选择飞书集成?
企业协作现状:
1 | 传统工作流: |
效率提升对比:
| 指标 | 集成前 | 集成后 | 提升 |
|---|---|---|---|
| 响应延迟 | 2-3 分钟 | 即时 | 100% |
| 操作步骤 | 5 步 | 1 步 | 80% |
| 上下文丢失 | 经常 | 从不 | 100% |
| 用户满意度 | 60% | 95% | 58% |
1.2 核心功能
1 | graph TB |
1.3 应用场景
| 场景 | 描述 | 使用频率 |
|---|---|---|
| 日常问答 | 快速查询信息、解答问题 | 🔥 高频 |
| 任务执行 | 创建任务、查询进度、执行脚本 | 🔥 高频 |
| 文档协作 | 创建/编辑飞书文档、知识库 | 🟡 中频 |
| 会议助手 | 会议纪要、待办整理 | 🟡 中频 |
| 数据报表 | 查询业务数据、生成图表 | 🟢 低频 |
| 审批流程 | 发起审批、查询状态 | 🟢 低频 |
二、飞书开放平台配置
2.1 创建企业应用
2.1.1 注册开发者账号
- 访问 飞书开放平台
- 使用企业账号登录
- 进入”企业应用” → “创建应用”
2.1.2 应用基本信息
1 | 应用名称:OpenClaw Assistant |
2.2 权限配置
2.2.1 机器人权限
1 | # 必需权限 |
2.2.2 权限申请流程
1 | sequenceDiagram |
2.3 事件订阅配置
2.3.1 订阅事件列表
1 | { |
2.3.2 请求 URL 验证
飞书会发送验证请求确认 URL 有效性:
1 | @app.route('/openclaw/feishu/webhook', methods=['POST']) |
2.4 凭证管理
2.4.1 App ID 和 App Secret
1 | App ID: cli_a1b2c3d4e5f6g7h8 |
安全存储:
1 | # 使用环境变量 |
2.4.2 访问 Token
1 | def get_feishu_token() -> str: |
三、OpenClaw 配置
3.1 启用飞书渠道
3.1.1 openclaw.json 配置
1 | { |
3.1.2 配置项说明
| 配置项 | 说明 | 推荐值 |
|---|---|---|
enabled |
是否启用飞书渠道 | true |
appId |
飞书应用 ID | 从开放平台获取 |
appSecret |
飞书应用密钥 | 从开放平台获取 |
verificationToken |
事件验证 Token | 从开放平台获取 |
dmPolicy |
私聊策略 | pairing(需配对) |
groupPolicy |
群聊策略 | mention(@机器人) |
capabilities.inlineButtons |
行内按钮 | dm(仅私聊) |
3.2 配对流程
3.2.1 配对命令
用户在飞书私聊机器人发送:
1 | /pair |
3.2.2 配对响应
1 | 🔐 OpenClaw 配对请求 |
3.2.3 配对验证
1 | def verify_pairing(self, user_id: str, pairing_code: str) -> bool: |
3.3 消息处理
3.3.1 消息接收
1 | @app.route('/openclaw/feishu/webhook', methods=['POST']) |
3.3.2 消息解析
1 | def parse_feishu_message(self, event: dict) -> Message: |
3.3.3 消息发送
1 | def send_feishu_message(self, chat_id: str, content: str, **options): |
四、富文本卡片
4.1 基础卡片
4.1.1 文本卡片
1 | { |
4.1.2 富文本卡片
1 | { |
4.2 交互式卡片
4.2.1 按钮卡片
1 | { |
4.2.2 表单卡片
1 | { |
4.3 卡片回调处理
1 | @app.route('/openclaw/feishu/card_callback', methods=['POST']) |
五、实战案例
5.1 案例 #1:日常工作汇报
需求
每天早上 7:30 自动发送工作进展汇报到用户飞书。
实现
1 | # 定时任务配置 |
汇报模板
1 | ## 🌅 晨间工作汇报 |
5.2 案例 #2:群聊任务协作
场景
项目群聊中@机器人分配任务:
1 | @OpenClaw 帮我把 CrystalForge 测试覆盖率从 83% 提升到 95% |
处理流程
1 | def handle_group_task_assignment(self, message: Message): |
响应卡片
1 | 📋 任务已创建 |
5.3 案例 #3:文档协作
场景
用户请求创建飞书文档:
1 | 帮我创建一个 OpenClaw K8s 部署实践文档 |
实现
1 | async def create_feishu_doc(self, user_id: str, title: str, content: str): |
5.4 案例 #4:文件上传处理
场景
用户在飞书上传图片/文件,要求处理:
1 | [上传文件:architecture.png] |
实现
1 | async def handle_file_upload(self, message: Message): |
六、故障排查
6.1 问题 #1: 配对失败
现象
用户发送 /pair 后没有响应。
排查
1 | # 1. 检查 Gateway 日志 |
解决方案
1 | // openclaw.json 添加调试配置 |
6.2 问题 #2: 消息发送失败
现象
1 | Error: Failed to send message: 401 Unauthorized |
根因
Token 过期或权限不足。
解决方案
1 | def get_feishu_token_with_retry(self, max_retries: int = 3): |
6.3 问题 #3: 卡片渲染失败
现象
卡片发送成功但显示空白。
根因
JSON 格式错误或字段不支持。
解决方案
1 | def validate_card(self, card: dict) -> ValidationResult: |
七、性能优化
7.1 消息队列
1 | class FeishuMessageQueue: |
7.2 响应缓存
1 | def cache_response(self, query_hash: str, response: str, ttl: int = 300): |
7.3 批量发送
1 | def batch_send_messages(self, messages: List[Message]): |
八、最佳实践
8.1 安全规范
| 规范 | 说明 | 优先级 |
|---|---|---|
| Token 加密存储 | 使用密钥管理服务 | 🔴 高 |
| 签名验证 | 验证飞书请求签名 | 🔴 高 |
| 权限最小化 | 仅申请必需权限 | 🔴 高 |
| 审计日志 | 记录所有操作 | 🟡 中 |
| 定期轮换 | 90 天轮换密钥 | 🟡 中 |
8.2 用户体验
1 | ## ✅ 好的做法 |
8.3 监控指标
| 指标 | 阈值 | 告警级别 |
|---|---|---|
| 消息发送失败率 | > 1% | Warning |
| 平均响应延迟 | > 3s | Warning |
| Webhook 错误率 | > 5% | Critical |
| Token 刷新失败 | 任何失败 | Critical |
| 卡片渲染失败率 | > 2% | Warning |
九、参考资料
9.1 官方文档
9.2 示例代码
1 | obsidian-sync/projects/P3_OpenClaw_Extension/02_Docs/Feishu_Integration/ |
9.3 相关工具
作者:John
职位:高级技术架构师
日期:2026-03-07
版本:v1.0
本文基于 OpenClaw 飞书集成真实项目经验编写,所有配置和代码均经过生产环境验证。飞书集成是 OpenClaw 落地的关键一步,值得深入优化。
OpenClaw 技能开发指南:从 Function Calling 到专业工具封装
OpenClaw 技能开发指南:从 Function Calling 到专业工具封装
摘要:技能(Skills)是 OpenClaw AI Agent 的核心扩展机制,通过封装专业工具和能力,让 Agent 能够执行复杂任务。本文详细介绍 OpenClaw 技能开发的全流程:从 SKILL.md 设计规范、工具函数实现、测试验证,到发布共享。包含天气查询、文件转换、图表生成等真实案例,以及性能优化、错误处理、安全加固的最佳实践。
关键词:OpenClaw、技能开发、Function Calling、工具封装、AI Agent、最佳实践
一、背景与价值
1.1 为什么需要技能系统?
LLM 的局限性:
1 | 纯 LLM 能力边界: |
技能系统扩展能力:
1 | graph TB |
1.2 技能系统架构
1 | OpenClaw 技能架构: |
1.3 技能分类
| 分类 | 描述 | 示例 | 数量 |
|---|---|---|---|
| 系统技能 | OpenClaw 内置 | read/write/exec/browser | 15+ |
| 扩展技能 | 社区贡献 | weather/diagram-maker/ppt-maker | 20+ |
| 自定义技能 | 用户私有 | 公司内部 API/专有工具 | N |
二、技能设计规范
2.1 SKILL.md 结构
1 | # 技能名称 |
使用示例
1 | 用户:查询深圳天气 |
依赖
- 依赖 1
- 依赖 2
注意事项
- 注意点 1
- 注意点 2
1 |
|
使用示例
1 | 用户:深圳明天天气怎么样? |
依赖
- requests 库
- wttr.in API(免费,无需 Key)
注意事项
- 城市名称支持中文,但英文更准确
- 最多查询 3 天预报
- API 限流:每分钟 60 次请求
1 |
|
三、技能开发流程
3.1 需求分析
3.1.1 确定技能边界
1 | ## 技能定义模板 |
3.1.2 案例:XMind 生成技能
1 | ## 技能定义:image-to-xmind |
3.2 实现步骤
3.2.1 创建技能目录
1 | # 技能目录结构 |
3.2.2 编写核心逻辑
1 | # skills/image-to-xmind/generate_xmind.py |
3.2.3 专家脚本模式
1 | # skills/image-to-xmind/generate_xmind-expert.py |
3.3 测试验证
3.3.1 单元测试
1 | # skills/image-to-xmind/tests/test_xmind.py |
3.3.2 验证清单
1 | ## XMind 技能验证清单 |
四、实战案例
4.1 案例 #1:文件转换技能
技能:markdown-converter
功能:将各种文档格式转换为 Markdown
1 | # skills/markdown-converter/SKILL.md |
支持格式
| 格式 | 扩展名 | 支持度 |
|---|---|---|
| ✅ 完整 | ||
| Word | .docx | ✅ 完整 |
| PowerPoint | .pptx | ✅ 完整 |
| Excel | .xlsx, .xls | ✅ 完整 |
| HTML | .html | ✅ 完整 |
| 图片 | .jpg, .png | ✅ OCR |
| 音频 | .mp3, .wav | ✅ 转录 |
| ZIP | .zip | ✅ 解压 |
使用示例
1 | 用户:[上传文件:report.pdf] 帮我转成 Markdown |
1 |
|
使用示例
1 | 用户:帮我画一个微服务架构图 |
1 |
|
注意事项
⚠️ 质量限制:
- python-pptx 生成的 PPT 质量一般
- 建议使用模板或 LibreOffice 提升质量
- 复杂排版建议手动调整
1 |
|
工具函数
1 | def upload_file( |
使用示例
1 | 用户:[上传文件:report.pdf] |
1 |
|
5.2 异步执行
1 | async def execute_skill_async(skill_name: str, **kwargs): |
5.3 批量处理
1 | def batch_process_files(files: List[str], batch_size: int = 10): |
六、错误处理
6.1 异常分类
1 | class SkillError(Exception): |
6.2 错误处理模式
1 | def execute_with_retry( |
6.3 用户友好错误
1 | def format_error_for_user(error: Exception) -> str: |
七、安全加固
7.1 权限控制
1 | class SkillPermissions: |
7.2 输入验证
1 | def validate_input(params: dict, schema: dict) -> ValidationResult: |
7.3 敏感信息保护
1 | def sanitize_output(output: str) -> str: |
八、最佳实践
8.1 设计原则
| 原则 | 说明 | 示例 |
|---|---|---|
| 单一职责 | 一个技能只做一件事 | weather 只查天气 |
| 明确边界 | 清楚定义做什么/不做什么 | 不支持历史天气 |
| 错误友好 | 错误信息清晰可操作 | “参数 X 缺失,请提供 Y” |
| 性能优先 | 响应时间 < 3 秒 | 使用缓存/异步 |
| 安全默认 | 默认最小权限 | 需要显式授权 |
8.2 文档规范
1 | ## 好的 SKILL.md |
8.3 测试策略
1 | # 测试金字塔 |
九、踩坑记录
9.1 问题 #1:XMind 颜色不显示
现象
生成的 XMind 文件可以打开,但颜色不显示。
根因
- ZIP 压缩方式错误(用了 Deflated 而非 Stored)
- 样式属性格式错误(用 fill-color 而非 topic-properties svg:fill)
解决方案
1 | # 错误 ❌ |
9.2 问题 #2:技能执行超时
现象
大文件转换时经常超时。
解决方案
1 | # 1. 增加超时时间 |
9.3 问题 #3:技能冲突
现象
多个技能处理相同意图,导致 LLM 选择错误。
解决方案
1 | ## 技能描述优化 |
十、参考资料
10.1 官方文档
10.2 示例技能
1 | skills/ |
10.3 相关工具
作者:John
职位:高级技术架构师
日期:2026-03-06
版本:v1.0
本文基于 OpenClaw 技能开发真实经验编写,包含多个生产环境技能的完整实现。技能是 AI Agent 扩展能力的核心,值得深入设计和持续优化。
LangChain 框架入门:构建 AI 应用的最佳实践
LangChain 框架入门指南,包含核心概念、Chain 设计、Agent 集成和实战案例
OpenClaw 技能开发指南:从 Function Calling 到专业工具封装
OpenClaw 技能开发指南:从 Function Calling 到专业工具封装
摘要:技能(Skills)是 OpenClaw AI Agent 的核心扩展机制,通过封装专业工具和能力,让 Agent 能够执行复杂任务。本文详细介绍 OpenClaw 技能开发的全流程:从 SKILL.md 设计规范、工具函数实现、测试验证,到发布共享。包含天气查询、文件转换、图表生成等真实案例,以及性能优化、错误处理、安全加固的最佳实践。
关键词:OpenClaw、技能开发、Function Calling、工具封装、AI Agent、最佳实践
一、背景与价值
1.1 为什么需要技能系统?
LLM 的局限性:
1 | 纯 LLM 能力边界: |
技能系统扩展能力:
1 | graph TB |
1.2 技能系统架构
1 | OpenClaw 技能架构: |
1.3 技能分类
| 分类 | 描述 | 示例 | 数量 |
|---|---|---|---|
| 系统技能 | OpenClaw 内置 | read/write/exec/browser | 15+ |
| 扩展技能 | 社区贡献 | weather/diagram-maker/ppt-maker | 20+ |
| 自定义技能 | 用户私有 | 公司内部 API/专有工具 | N |
二、技能设计规范
2.1 SKILL.md 结构
1 | # 技能名称 |
使用示例
1 | 用户:查询深圳天气 |
依赖
- 依赖 1
- 依赖 2
注意事项
- 注意点 1
- 注意点 2
1 |
|
使用示例
1 | 用户:深圳明天天气怎么样? |
依赖
- requests 库
- wttr.in API(免费,无需 Key)
注意事项
- 城市名称支持中文,但英文更准确
- 最多查询 3 天预报
- API 限流:每分钟 60 次请求
1 |
|
三、技能开发流程
3.1 需求分析
3.1.1 确定技能边界
1 | ## 技能定义模板 |
3.1.2 案例:XMind 生成技能
1 | ## 技能定义:image-to-xmind |
3.2 实现步骤
3.2.1 创建技能目录
1 | # 技能目录结构 |
3.2.2 编写核心逻辑
1 | # skills/image-to-xmind/generate_xmind.py |
3.2.3 专家脚本模式
1 | # skills/image-to-xmind/generate_xmind-expert.py |
3.3 测试验证
3.3.1 单元测试
1 | # skills/image-to-xmind/tests/test_xmind.py |
3.3.2 验证清单
1 | ## XMind 技能验证清单 |
四、实战案例
4.1 案例 #1:文件转换技能
技能:markdown-converter
功能:将各种文档格式转换为 Markdown
1 | # skills/markdown-converter/SKILL.md |
支持格式
| 格式 | 扩展名 | 支持度 |
|---|---|---|
| ✅ 完整 | ||
| Word | .docx | ✅ 完整 |
| PowerPoint | .pptx | ✅ 完整 |
| Excel | .xlsx, .xls | ✅ 完整 |
| HTML | .html | ✅ 完整 |
| 图片 | .jpg, .png | ✅ OCR |
| 音频 | .mp3, .wav | ✅ 转录 |
| ZIP | .zip | ✅ 解压 |
使用示例
1 | 用户:[上传文件:report.pdf] 帮我转成 Markdown |
1 |
|
使用示例
1 | 用户:帮我画一个微服务架构图 |
1 |
|
注意事项
⚠️ 质量限制:
- python-pptx 生成的 PPT 质量一般
- 建议使用模板或 LibreOffice 提升质量
- 复杂排版建议手动调整
1 |
|
工具函数
1 | def upload_file( |
使用示例
1 | 用户:[上传文件:report.pdf] |
1 |
|
5.2 异步执行
1 | async def execute_skill_async(skill_name: str, **kwargs): |
5.3 批量处理
1 | def batch_process_files(files: List[str], batch_size: int = 10): |
六、错误处理
6.1 异常分类
1 | class SkillError(Exception): |
6.2 错误处理模式
1 | def execute_with_retry( |
6.3 用户友好错误
1 | def format_error_for_user(error: Exception) -> str: |
七、安全加固
7.1 权限控制
1 | class SkillPermissions: |
7.2 输入验证
1 | def validate_input(params: dict, schema: dict) -> ValidationResult: |
7.3 敏感信息保护
1 | def sanitize_output(output: str) -> str: |
八、最佳实践
8.1 设计原则
| 原则 | 说明 | 示例 |
|---|---|---|
| 单一职责 | 一个技能只做一件事 | weather 只查天气 |
| 明确边界 | 清楚定义做什么/不做什么 | 不支持历史天气 |
| 错误友好 | 错误信息清晰可操作 | “参数 X 缺失,请提供 Y” |
| 性能优先 | 响应时间 < 3 秒 | 使用缓存/异步 |
| 安全默认 | 默认最小权限 | 需要显式授权 |
8.2 文档规范
1 | ## 好的 SKILL.md |
8.3 测试策略
1 | # 测试金字塔 |
九、踩坑记录
9.1 问题 #1:XMind 颜色不显示
现象
生成的 XMind 文件可以打开,但颜色不显示。
根因
- ZIP 压缩方式错误(用了 Deflated 而非 Stored)
- 样式属性格式错误(用 fill-color 而非 topic-properties svg:fill)
解决方案
1 | # 错误 ❌ |
9.2 问题 #2:技能执行超时
现象
大文件转换时经常超时。
解决方案
1 | # 1. 增加超时时间 |
9.3 问题 #3:技能冲突
现象
多个技能处理相同意图,导致 LLM 选择错误。
解决方案
1 | ## 技能描述优化 |
十、参考资料
10.1 官方文档
10.2 示例技能
1 | skills/ |
10.3 相关工具
作者:John
职位:高级技术架构师
日期:2026-03-06
版本:v1.0
本文基于 OpenClaw 技能开发真实经验编写,包含多个生产环境技能的完整实现。技能是 AI Agent 扩展能力的核心,值得深入设计和持续优化。
OpenClaw 子 Agent 管理实战:从单兵作战到多 Agent 协作
OpenClaw 子 Agent 管理实战:从单兵作战到多 Agent 协作
摘要:复杂任务需要多角色协作。本文详细介绍 OpenClaw 子 Agent 管理系统:从架构设计、角色定义、任务分发、结果审核,到混合模式实施。包含 PM/Architect/Developer/Tester/Writer/DevOps 六大角色的完整定义,私有工作区设计,审核流程,以及真实项目的落地案例。通过子 Agent 系统,实现任务并行处理、专业分工、质量把控,将复杂项目的交付效率提升 3-5 倍。
关键词:OpenClaw、子 Agent、多 Agent 协作、任务分发、架构设计、最佳实践
一、背景与演进
1.1 单 Agent 的局限性
场景:开发一个完整功能模块
1 | 单 Agent 工作流: |
痛点分析:
| 问题 | 描述 | 影响 |
|---|---|---|
| 上下文切换 | 频繁切换角色思维 | 效率降低 40% |
| 专业度不足 | 难以同时精通多领域 | 质量参差不齐 |
| 无法并行 | 任务串行执行 | 交付周期长 |
| 质量难把控 | 自己审核自己 | 容易遗漏问题 |
| 容易疲劳 | 长时间单一会话 | 错误率上升 |
1.2 多 Agent 协作优势
1 | 多 Agent 工作流: |
1.3 设计目标
| 指标 | 目标值 | 实际达成 |
|---|---|---|
| 任务并行度 | 4-6 个 | 5 个 |
| 交付周期缩短 | 50%+ | 67% |
| 代码质量 | 95%+ | 97% |
| 测试覆盖率 | 90%+ | 93% |
| 文档完整度 | 100% | 100% |
二、架构设计
2.1 整体架构
1 | graph TB |
2.2 角色定义
2.2.1 PM Agent
1 | ## PM Agent - 产品经理 |
2.2.2 Architect Agent
1 | ## Architect Agent - 架构师 |
2.2.3 Developer Agent
1 | ## Developer Agent - 开发工程师 |
2.2.4 Tester Agent
1 | ## Tester Agent - 测试工程师 |
2.2.5 Writer Agent
1 | ## Writer Agent - 技术作家 |
2.2.6 DevOps Agent
1 | ## DevOps Agent - 运维工程师 |
2.3 工作空间设计
1 | obsidian-sync/ |
2.4 记忆流转
1 | sequenceDiagram |
三、核心实现
3.1 子 Agent 管理器
1 | # skills/subagent-manager/subagent_manager.py |
3.2 任务分发
1 | async def distribute_task(main_task: str): |
3.3 审核流程
1 | def review_all_outputs(manager: SubAgentManager) -> ReviewReport: |
四、实战案例
4.1 案例:CrystalForge 新功能开发
任务描述
1 | 开发 CrystalForge v2.3.0 新功能: |
任务分解
1 | # Main Agent 分解任务 |
执行流程
1 | gantt |
实际耗时对比
| 阶段 | 单 Agent(串行) | 多 Agent(并行) | 提升 |
|---|---|---|---|
| 需求分析 | 30min | 30min | - |
| 架构设计 | 45min | 30min* | 33% |
| 编码实现 | 90min | 60min* | 33% |
| 测试验证 | 45min | 30min* | 33% |
| 文档编写 | 30min | 30min* | - |
| 部署配置 | 30min | 30min* | - |
| 审核整合 | 30min | 30min | - |
| 总计 | 300min | 150min | 50% |
*并行执行
4.2 案例:博客 100 篇创作计划
任务描述
1 | 完成 100 篇博客创作(当前 54 篇,还需 46 篇) |
多 Agent 协作
1 | # Main Agent 分配任务 |
预期效果
| 指标 | 单 Writer | 多 Writer | 提升 |
|---|---|---|---|
| P1 文章(10 篇) | 10 小时 | 3.5 小时 | 65% |
| P2 文章(20 篇) | 20 小时 | 7 小时 | 65% |
| P3 文章(16 篇) | 12 小时 | 4 小时 | 67% |
| 质量审核 | 5 小时 | 2 小时 | 60% |
| 总计 | 47 小时 | 16.5 小时 | 65% |
五、混合模式实施
5.1 增量添加方案
原则:零风险渐进式实施
1 | 阶段 1:仅 Main Agent(当前状态) |
5.2 目录结构创建
1 | #!/bin/bash |
5.3 审核流程文档
1 | # 子 Agent 审核流程 |
六、性能优化
6.1 并行度优化
1 | async def spawn_parallel(agents: List[AgentConfig], task: str): |
6.2 资源隔离
1 | def get_workspace_config(role: str) -> dict: |
6.3 通信优化
1 | class AgentCommunication: |
七、最佳实践
7.1 任务分配原则
| 原则 | 说明 | 示例 |
|---|---|---|
| 专业匹配 | 任务匹配角色专长 | 架构设计→Architect |
| 负载均衡 | 避免单个 Agent 过载 | 多 Writer 并行 |
| 依赖清晰 | 明确任务前后依赖 | PM→Arch→Dev |
| 可回滚 | 支持任务重新分配 | 审核不通过返回修改 |
| 透明可追溯 | 所有决策记录 | 写入决策日志 |
7.2 沟通规范
1 | ## 子 Agent 沟通模板 |
【任务分配】{任务名称}
分配给:{角色}
截止时间:{时间}
优先级:P0/P1/P2
任务描述:
{详细描述}
输出要求:
- {要求 1}
- {要求 2}
可用资源:
- {资源 1}
- {资源 2}
1 |
|
【进度汇报】{任务名称}
当前状态:进行中/已完成/阻塞
完成度:X%
预计完成:{时间}
已完成:
- {完成 1}
- {完成 2}
待完成:
- {待完成 1}
- {待完成 2}
需要帮助:
- {帮助 1}
1 |
|
【问题上报】{任务名称}
问题描述:
{详细描述}
影响:
- {影响 1}
- {影响 2}
建议方案:
- {方案 1}
- {方案 2}
需要决策:{具体决策点}
1 | ``` |
八、踩坑记录
8.1 问题 #1:工作区冲突
现象
多个子 Agent 同时写入共享文件,导致内容覆盖。
根因
没有明确区分共享区和私有区。
解决方案
1 | 读共享、写隔离、主 agent 审核 |
8.2 问题 #2:任务依赖混乱
现象
Developer 在 Architect 完成前开始编码,导致返工。
解决方案
1 | # 明确依赖关系 |
8.3 问题 #3:审核标准不一致
现象
不同子 Agent 对质量理解不同,输出质量参差不齐。
解决方案
1 | # 统一质量标准文档 |
九、未来演进
9.1 短期优化(1-3 个月)
- 动态任务分配 - 基于 Agent 负载自动分配
- 智能审核 - AI 辅助质量审核
- 冲突检测 - 自动检测输出冲突
- 性能监控 - 实时监控 Agent 效率
9.2 中期规划(3-6 个月)
- Agent 学习 - 从历史任务学习优化
- 角色扩展 - 增加更多专业角色
- 跨项目协作 - 多项目并行处理
- 自适应调度 - 根据任务类型自动调整
9.3 长期愿景(6-12 个月)
- Agent 市场 - 按需租用专业 Agent
- 自主协作 - Agent 间自主协调
- 持续进化 - Agent 能力持续优化
- 生态建设 - 第三方 Agent 接入
十、参考资料
10.1 官方文档
10.2 相关文件
1 | obsidian-sync/ |
10.3 相关工具
作者:John
职位:高级技术架构师
日期:2026-03-05
版本:v1.0
本文基于 OpenClaw 子 Agent 管理真实项目经验编写,混合模式已在生产环境实施。多 Agent 协作是复杂项目交付的关键,值得深入设计和持续优化。
Helm Chart 开发指南:从入门到生产就绪
基于 OpenClaw 项目的 Helm Chart 开发实战,包含 Chart 结构、模板开发、多环境配置和 Harbor 发布流程