[← 第 11 章](/openclaw-tutorial/11-%E9%AB%98%E7%BA%A7%E5%9C%BA%E6%99%AF-%E7%AC%AC%E4%B8%89%E6%96%B9%E5%B9%B3%E5%8F%B0%E9%9B%86%E6%88%90.html) · [📑 目录](/openclaw-tutorial/) · [📋 大纲](/openclaw-tutorial/OUTLINE.html) · [第 13 章 →](/openclaw-tutorial/13-%E6%95%99%E7%A8%8B%E8%87%AA%E5%8A%A8%E6%9B%B4%E6%96%B0%E4%B8%8E%E4%BB%93%E5%BA%93%E7%BB%B4%E6%8A%A4.html)

第 12 章:实践案例与常见问题

difficulty time chapter

难度: ⭐⭐⭐ 进阶 预计阅读: 22 分钟 前置章节: 建议完成全部前置章节

本章汇总多个 OpenClaw 实践案例,从个人知识管理到团队协作自动化,并整理最常见的问题解答,帮助你快速解决实际使用中遇到的各种情况。

📑 本章目录


12.1 案例一:个人知识助手

需求场景

构建 7×24 小时运行的个人知识管理助手,自动搜索、整理和归档资料,形成个人知识库。

架构设计

定时触发(Cron) → 网络搜索(Tavily) → 内容摘要(AI) → 存储(Memory) → 日报(飞书)

使用的 Skills

Skill 用途 关键配置
tavily-search 网络搜索 TAVILY_API_KEY
memory 知识存储 分类标签体系
feishu 消息推送 通道配置

完整配置

# workflow-knowledge.yaml
name: 个人知识助手
schedule:
  type: cron
  cron: "0 8,12,18 * * *"  # 每天 3 次

tasks:
  - name: search-and-save
    prompt: |
      1. 搜索今日关于 [AI, 编程, 产品] 的热门话题
      2. 对每篇文章生成 200 字摘要
      3. 按标签分类存入记忆
      4. 生成今日知识简报
    timeout: 600

  - name: daily-digest
    prompt: |
      1. 汇总今天收集的所有知识点
      2. 生成结构化日报
      3. 通过飞书发送

部署步骤

以下步骤将引导你从零开始部署个人知识助手。确保 OpenClaw 已正确安装并且网络可以访问 Tavily API,按顺序执行即可完成配置。

# 1. 确认 tavily-search skill 已安装
ls ~/.openclaw/workspace/skills/tavily-search/SKILL.md

# 2. 设置 Tavily API Key
export TAVILY_API_KEY="your-key-here"

# 3. 注册 Cron 任务
python3 -m json.tool ~/.openclaw/cron/jobs.json  # 确认语法正确

# 4. 验证运行
openclaw doctor

实际效果

部署完成并稳定运行后,你将获得一个完全自动化的知识采集与整理系统。以下是实际运行一个月后的典型产出数据:


12.2 案例二:项目监控机器人

应用背景

监控多个 GitHub 项目状态,跟踪 PR、Issue、CI 状态,自动推送摘要到飞书群。

实现步骤

第一步:安装必要 Skills

# 确认 github skill 已安装
ls ~/.openclaw/workspace/skills/github/SKILL.md

# 配置 GitHub 认证
gh auth login

第二步:创建监控 Workflow

# workflow-github-monitor.yaml
name: GitHub 项目监控
schedule:
  type: cron
  cron: "0 9,17 * * 1-5"  # 工作日早晚各一次

config:
  repos:
    - owner/repo-a
    - owner/repo-b

tasks:
  - name: check-status
    prompt: |
      对以下仓库执行检查:
      1. gh pr list --state open —— 统计待合并 PR
      2. gh issue list --state open —— 统计待解决 Issue
      3. gh run list --limit 3 —— 检查最近 CI 状态
      4. 生成状态报告发到飞书
    timeout: 300

第三步:注册 Cron 任务

{
  "name": "GitHub 项目监控",
  "schedule": {"kind": "cron", "expr": "0 9,17 * * 1-5"},
  "payload": {
    "kind": "agentTurn",
    "message": "执行 GitHub 项目监控 workflow"
  }
}

第四步:验证并观察

# 手动触发一次测试
openclaw message send --channel feishu --message "测试 GitHub 监控 workflow"

# 检查 Cron 任务状态
python3 -m json.tool ~/.openclaw/cron/jobs.json

产出与收益

通过将监控逻辑完全交给 Agent 自动执行,团队可以把精力集中在代码开发和功能迭代上,而不必频繁切换到 GitHub 界面查看项目状态。长期运行后,历史推送记录还可以作为项目进度的追溯依据,帮助团队在回顾会议中快速复盘关键节点。


12.3 案例三:教程自动生成

项目概述

使用 complex-task-automator Skill 自动生成多章节教程(即本教程的生成方式)。

核心架构

章节大纲(config) → 逐章生成(AI) → 质量检查(脚本) → Git 提交 → 飞书通知

关键组件

组件 作用 文件路径
workflow-full.yaml 定义完整工作流 workflows/
write_chapter.py 章节生成引擎,内置知识库 scripts/
analyze_progress.py 进度追踪和质量评估 scripts/
git_workflow.py 自动 commit/push scripts/
batch_runner.py 批量连续生成 scripts/
health_check.py 健康检查和告警 scripts/

配置要点

# 关键配置
config:
  MAX_CHAPTERS_PER_RUN: 3    # 每次最多生成 3 章
  COOLDOWN_SECONDS: 30        # 章节间冷却
  MIN_WORD_COUNT: 500         # 最低字数要求
  MIN_QUALITY_SCORE: 85       # 最低质量分

质量检查脚本示例

#!/usr/bin/env python3
# quality-check.py — 章节质量检查
import re, sys

def check_chapter(filepath):
    with open(filepath) as f:
        content = f.read()

    issues = []

    # 检查字数
    text = re.sub(r'```[\s\S]*?```', '', content)
    word_count = len(re.sub(r'\s+', '', text))
    if word_count < 1500:
        issues.append(f"字数不足: {word_count} < 1500")

    # 检查标题层级
    headers = re.findall(r'^(#{1,6})\s', content, re.M)
    levels = [len(h) for h in headers]
    for i in range(1, len(levels)):
        if levels[i] - levels[i-1] > 1:
            issues.append(f"标题层级跳跃: H{levels[i-1]} → H{levels[i]}")

    # 检查代码块语言标注
    code_blocks = re.findall(r'```(\w*)', content)
    unlabeled = sum(1 for lang in code_blocks if not lang)
    if unlabeled:
        issues.append(f"{unlabeled} 个代码块缺少语言标注")

    if issues:
        print(f"❌ {filepath}: {len(issues)} 个问题")
        for i in issues:
            print(f"   - {i}")
        return False
    else:
        print(f"✅ {filepath}: 通过")
        return True

if __name__ == "__main__":
    filepath = sys.argv[1] if len(sys.argv) > 1 else "chapter.md"
    check_chapter(filepath)

最终成果

这一案例展示了 complex-task-automator 在长篇内容创作场景下的强大能力。整个流程无需人工介入,从大纲解析、逐章生成到质量检测和 Git 提交均由 Agent 自动完成。生成的内容可作为初稿直接使用,也可在此基础上进行人工润色和补充,大幅缩短内容创作周期。


12.4 案例对比总结

维度 个人知识助手 项目监控机器人 教程自动生成
复杂度 ⭐⭐ ⭐⭐⭐ ⭐⭐⭐⭐
核心 Skill tavily-search + memory github + feishu complex-task-automator
触发方式 Cron 定时 Cron 定时 手动 + Cron
输出形式 飞书日报 飞书群消息 Markdown + Git
适合场景 个人学习 团队协作 内容创作
设置耗时 ~30 分钟 ~1 小时 ~2 小时

12.5 常见问题汇总

系统与资源

Q1: OpenClaw 占用多少系统资源?

A: Gateway 常驻内存约 100-200MB,Agent 会话按需启动,每个约 50-100MB。空闲时 CPU 占用接近 0。

# 查看资源占用
ps aux | grep openclaw
top -p $(pgrep -d',' openclaw)

Q2: 支持哪些操作系统?

A: 目前支持 Linux(推荐 Ubuntu 22.04+)和 macOS。Windows 需通过 WSL2 运行。

系统 支持状态 备注
Ubuntu 22.04+ ✅ 推荐 原生支持,性能最佳
Debian 11+ ✅ 支持 需手动安装 Node.js 18+
macOS 12+ ✅ 支持 Intel 和 Apple Silicon 均可
Windows (WSL2) ⚠️ 可用 需先安装 WSL2 + Ubuntu
CentOS/RHEL ⚠️ 未测试 理论可行,需自行验证

Q3: 数据存储在哪里?安全吗?

A: 所有数据存储在 ~/.openclaw/ 目录下,完全本地化,不上传到云端。敏感凭证存储在 credentials/ 子目录中。建议定期备份:

# 快速备份
tar -czf ~/openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

模型与配置

Q4: 支持哪些 AI 模型?

A: 支持主流模型:

提供商 模型 推荐场景
OpenAI GPT-4.1, GPT-4o 通用场景,均衡性能
Anthropic Claude Opus, Claude Sonnet 长文本、复杂推理
Google Gemini Pro 多模态任务
本地 Ollama (Llama, Qwen 等) 隐私敏感场景

通过 openclaw.json 中的 model 字段切换。

Q5: 如何切换模型?

{
  "agent": {
    "model": "claude-sonnet-4-20250514",
    "provider": "anthropic"
  }
}
# 或通过命令行切换
openclaw config set agent.model "gpt-4.1"
openclaw config set agent.provider "openai"
openclaw gateway reload

网络与连接

Q6: Agent 无法连接外部 API?

A: 检查步骤:

  1. 确认网络连通:curl -I https://api.openai.com
  2. 检查代理设置:echo $HTTP_PROXY
  3. 验证 API Key 有效性
  4. 查看日志:~/.openclaw/logs/
# 快速网络诊断
curl -s -o /dev/null -w "HTTP 状态: %{http_code}, 耗时: %{time_total}s\n" https://api.openai.com/v1/models

Q7: 飞书消息发送失败?

A: 常见原因与解决:

原因 症状 解决方法
Token 过期 返回 401 重新配对设备 openclaw pair
网络不通 超时 检查防火墙 curl feishu.cn
频率限制 返回 429 降低发送频率,增加间隔
消息格式错误 返回 400 检查消息内容长度和格式

进阶:架构设计模式

在实际项目中应用 OpenClaw 时,以下架构设计模式值得参考:


注意事项与常见错误

实际使用中最常见的踩坑总结和应对策略:

常见错误 场景 建议
过度依赖单一模型 所有任务都用最贵的模型 根据任务复杂度选择合适模型,简单任务用轻量模型
Skill 职责不清 一个 Skill 做太多事 遵循单一职责原则,每个 Skill 专注一件事
缺乏监控告警 线上故障无法及时发现 配置 openclaw hooks 失败通知,接入飞书告警群
配置散落各处 生产环境配置难以管理 统一使用 openclaw.json 管理,敏感信息走环境变量

⚠️ 最佳实践:每个实践案例投入生产前,务必经过 开发→测试→灰度→全量 的完整流程,避免未经验证的配置直接上线。


进阶:案例架构设计模式

从实践案例中提炼出的通用架构模式:

模式 说明 典型场景
单 Agent 单任务 最简部署,一个 Agent 处理所有请求 个人助手
多 Agent 分工 不同 Agent 负责不同领域 团队协作、多业务线
Agent + Cron 混合 Agent 交互 + 定时自动化 日报生成、监控告警
Pipeline 编排 多步骤工作流自动化 教程维护、数据处理

注意事项与常见错误

实践中常见的错误模式:

常见错误 后果 正确做法
过度依赖 AI 判断 关键操作出错难恢复 高风险操作加人工审批(exec-approvals)
Prompt 写得不够具体 Agent 输出不稳定 使用 SOUL.md 明确行为规范
忽视记忆管理 上下文越来越嘈杂 定期清理和合并记忆


进阶:案例架构设计模式

从实践案例提炼的通用架构模式:

模式 说明 典型场景
单 Agent 单任务 最简部署 个人助手
多 Agent 分工 不同领域 团队协作
Agent+Cron 混合 交互加自动化 日报生成
Pipeline 编排 多步骤工作流 教程维护

注意事项与常见错误

实践中常见错误模式:

常见错误 后果 正确做法
过度依赖 AI 判断 关键操作出错 高风险加审批
Prompt 不够具体 输出不稳定 用 SOUL.md 规范
忽视记忆管理 上下文嘈杂 定期清理合并


实操练习

练习 1:搭建个人知识助手

按照案例一的步骤,搭建一个完整的个人知识助手:

# 第 1 步:确认必要 Skills 已安装
ls ~/.openclaw/workspace/skills/tavily-search/SKILL.md 2>/dev/null \
  && echo "✅ tavily-search 已安装" \
  || echo "❌ 需要安装 tavily-search"

ls ~/.openclaw/workspace/skills/memory/SKILL.md 2>/dev/null \
  && echo "✅ memory 已安装" \
  || echo "❌ 需要安装 memory"

# 第 2 步:创建 workflow 配置文件
mkdir -p ~/.openclaw/workspace/workflows
cat > ~/.openclaw/workspace/workflows/knowledge-assistant.yaml << 'EOF'
name: 个人知识助手
schedule:
  type: cron
  cron: "0 9 * * *"
tasks:
  - name: daily-search
    prompt: |
      搜索今日 AI 领域热门话题,生成摘要并存入记忆
    timeout: 300
EOF

echo "✅ workflow 配置已创建"

# 第 3 步:验证配置
python3 -c "
import yaml
with open('$HOME/.openclaw/workspace/workflows/knowledge-assistant.yaml') as f:
    config = yaml.safe_load(f)
    print(f'Workflow: {config[\"name\"]}')
    print(f'任务数: {len(config[\"tasks\"])}')
"

练习 2:创建 GitHub 项目状态检查脚本

# 第 1 步:创建检查脚本
cat > /tmp/gh-check.sh << 'EOF'
#!/bin/bash
# gh-check.sh — GitHub 项目快速状态检查
REPO=${1:-"nicepkg/openclaw"}

echo "=== $REPO 状态检查 ==="

# 检查 gh CLI 是否可用
if ! command -v gh &> /dev/null; then
  echo "❌ 需要安装 GitHub CLI: https://cli.github.com/"
  exit 1
fi

echo "📋 Open PRs:"
gh pr list --repo "$REPO" --state open --limit 5 2>/dev/null || echo "  (无法访问)"

echo ""
echo "🐛 Open Issues:"
gh issue list --repo "$REPO" --state open --limit 5 2>/dev/null || echo "  (无法访问)"

echo ""
echo "🔄 Recent CI Runs:"
gh run list --repo "$REPO" --limit 3 2>/dev/null || echo "  (无法访问)"

echo "=== 检查完成 ==="
EOF

chmod +x /tmp/gh-check.sh

# 第 2 步:运行检查(替换为你的仓库)
# bash /tmp/gh-check.sh owner/repo
echo "请运行: bash /tmp/gh-check.sh <owner/repo>"

练习 3:编写章节质量检查脚本

# 第 1 步:创建质量检查脚本
cat > /tmp/quality-check.sh << 'QEOF'
#!/bin/bash
# quality-check.sh — Markdown 章节质量快速检查
FILE=${1:-"chapter.md"}

if [ ! -f "$FILE" ]; then
  echo "❌ 文件不存在: $FILE"
  exit 1
fi

echo "=== 质量检查: $FILE ==="

# 字数统计
CHARS=$(wc -m < "$FILE")
echo "📊 总字符数: $CHARS"
[ "$CHARS" -ge 1500 ] && echo "  ✅ >= 1500" || echo "  ❌ < 1500"

# 代码块语言检查
UNLABELED=$(grep -c '^```$' "$FILE" || true)
echo "📝 未标注语言的代码块: $UNLABELED"
[ "$UNLABELED" -eq 0 ] && echo "  ✅ 全部已标注" || echo "  ⚠️ 有 $UNLABELED 个需标注"

# 标题层级检查
echo "📑 标题结构:"
grep '^#' "$FILE" | head -15

echo "=== 检查完成 ==="
QEOF

chmod +x /tmp/quality-check.sh

# 第 2 步:对当前教程文件运行检查
# bash /tmp/quality-check.sh "03-Skills 插件体系与批量开发.md"
echo "请运行: bash /tmp/quality-check.sh <markdown-file>"

常见问题 (FAQ) — 补充

Q8: 案例配置可以直接用吗?

A: 需要根据实际环境修改 API Key、仓库地址等配置。建议先用 --dry-run 模式测试,确认无误后再启用定时任务。

Q9: 如何查看更多实践案例?

A: 访问以下资源:

Q10: 多个 Workflow 同时运行会冲突吗?

A: OpenClaw 支持并发执行,但建议:

  1. 设置合理的 timeout 防止任务挂起
  2. 避免多个 workflow 写入同一个文件
  3. 使用 maxConcurrent 限制并发数
{
  "agent": {
    "maxConcurrent": 3
  }
}

外部参考链接


参考来源

来源 链接 可信度 说明
OpenClaw 官方文档 https://docs.OpenClaw.ai A 安装, 配置, 命令
OpenClaw GitHub 仓库 https://github.com/OpenClaw/OpenClaw A 源码, Issues, Release
ClawHub Skills 平台 https://hub.OpenClaw.ai A Skills, 市场, 安装

Troubleshooting

问题 1:案例复现时 Skill 安装失败,提示 skill not found

症状:按照案例步骤执行 clawhub install 后,提示找不到对应的 Skill 包。

解决方案

# 确认 ClawHub 源配置正确
openclaw config get hub.registry

# 刷新 Skill 索引缓存
clawhub update

# 重新安装指定 Skill
clawhub install tavily-search --force

# 如果仍然失败,检查网络连通性
curl -I https://hub.openclaw.ai

问题 2:Cron 任务配置迁移到新环境后不生效

症状:将 cron/jobs.json 复制到新设备后,定时任务未按计划执行。

解决方案

# 验证 jobs.json 格式是否正确
python3 -m json.tool ~/.openclaw/cron/jobs.json

# 重新加载 Cron 配置
openclaw cron reload

# 查看 Cron 任务状态
openclaw cron list

# 手动触发一次以验证
openclaw cron trigger <job-id>

问题 3:知识助手运行正常但飞书通知未收到

症状:Cron 任务执行成功,知识库有新条目,但飞书群未收到每日简报消息。

解决方案

# 检查飞书凭证是否有效
openclaw credential list | grep feishu

# 测试飞书 Webhook 连通性
curl -X POST <your-webhook-url>   -H "Content-Type: application/json"   -d '{"msg_type":"text","content":{"text":"OpenClaw 连通性测试"}}'

# 查看 delivery-queue 是否有积压
ls -la ~/.openclaw/delivery-queue/ | wc -l

本章小结

本章通过三个完整的实践案例,展示了 OpenClaw 的实际应用能力:

建议从最简单的「个人知识助手」案例开始实践,逐步过渡到更复杂的自动化场景。


[← 上一章:高级场景-第三方平台集成](/openclaw-tutorial/11-%E9%AB%98%E7%BA%A7%E5%9C%BA%E6%99%AF-%E7%AC%AC%E4%B8%89%E6%96%B9%E5%B9%B3%E5%8F%B0%E9%9B%86%E6%88%90.html) · [📑 返回目录](/openclaw-tutorial/) · [下一章:教程自动更新与仓库维护 →](/openclaw-tutorial/13-%E6%95%99%E7%A8%8B%E8%87%AA%E5%8A%A8%E6%9B%B4%E6%96%B0%E4%B8%8E%E4%BB%93%E5%BA%93%E7%BB%B4%E6%8A%A4.html)