第七部分：智能体（Agents）入门与实用案例

前六部分系统地讲解了 OpenClaw 的架构、配置和安全体系。本部分将视角从"理解系统"切换到"设计智能体"——你将学会如何从零开始设计一个有用的智能体，掌握人格定义、工具编排、记忆策略和工作流串联的实战技巧，并通过六个完整案例获得可直接复用的智能体模板。

第 22 章：从零设计一个智能体

22.1 智能体设计思维框架

设计一个智能体不是"配个 API Key 就开聊"。一个高质量的智能体需要回答以下五个问题：

1. 它是谁？        → IDENTITY.md + SOUL.md
2. 它能做什么？    → 工具策略 + 技能配置
3. 它记得什么？    → 记忆策略 + AGENTS.md
4. 谁能使用它？    → 渠道策略 + DM Policy
5. 它有多安全？    → 沙箱 + 工具限制 + 审批

这五个问题对应 OpenClaw 的五个核心配置维度。让我们从最简单的案例开始逐步构建。

22.2 最小可用智能体

一个最小可用的智能体只需要三步：

第一步：创建智能体

bash

openclaw agents add my-first-agent

第二步：编辑人格文件

markdown

# SOUL.md
你是一个友好、简洁的中文助手。
- 回答问题时直接给出答案
- 不确定时说"我不确定"
- 使用简体中文

第三步：启动并测试

bash

# 向智能体发送测试消息
openclaw agent --agent my-first-agent --message "你好，介绍一下你自己"

就这么简单——你已经有了一个可以对话的智能体。但这只是起点。

22.3 智能体设计清单

在投入生产之前，按以下清单逐项检查：

身份与人格

检查项	文件	说明
名称与角色	`IDENTITY.md`	一行简洁声明
人格定义	`SOUL.md`	性格、语气、边界
用户画像	`USER.md`	用户信息和偏好

能力与权限

检查项	配置位置	说明
工具策略	`tools.profile` / `tools.deny`	能用什么工具
技能加载	`skills/` 目录	需要哪些技能
模型选择	`model.primary` / `model.fallbacks`	用什么模型

记忆与上下文

检查项	配置位置	说明
操作指引	`AGENTS.md`	行为规则和工作流
长期记忆	`MEMORY.md`	跨会话持久信息
会话策略	`session.reset` / `session.dmScope`	会话生命周期

安全与访问

检查项	配置位置	说明
DM 策略	`channels.<channel>.dmPolicy`	谁能联系
沙箱配置	`sandbox.mode`	隔离级别
工具审批	`tools.elevated`	是否需要人工审批

22.4 人格设计的艺术

人格文件（SOUL.md）不是装饰——它直接影响智能体的输出质量和用户体验。

反模式：模糊的人格定义

markdown

# ❌ 不好的 SOUL.md
你是一个 AI 助手，帮助用户完成各种任务。

这种定义太泛了，模型会用默认的"通用 AI"风格回复。

正确做法：具体且有约束

markdown

# ✅ 好的 SOUL.md
你是"小码"，一个专注于全栈开发的技术助手。

## 性格
- 像经验丰富的同事一样交流，不是客服
- 直接给出方案，不说"当然可以，让我帮您..."
- 发现代码有问题时直接指出，不需要铺垫

## 风格
- 代码示例优先于文字解释
- 中文交流，代码注释用英文
- 优先推荐简单方案，复杂方案标注"进阶"

## 边界
- 不讨论与技术无关的话题
- 不生成完整项目（引导用户分步构建）
- 遇到安全相关问题时，默认选择最安全的方案

人格维度参考

维度	选项示例	影响
语气	正式/随意/幽默/严肃	回复的措辞风格
详细度	精简/适中/详尽	回复的长度和深度
主动性	被动/适度/主动	是否主动建议和补充
专业度	通用/领域专家/初学者友好	术语使用和解释深度
边界	宽泛/适中/严格	拒绝不相关请求的力度

22.5 操作指引（AGENTS.md）的编写原则

AGENTS.md 是智能体的"员工手册"，定义它的工作流程和行为规则。

编写原则

1. 使用命令式语气

markdown

# ✅ 好
- 在执行文件操作前，先确认目标路径存在
- 每次完成代码修改后，运行 `bun test` 验证

# ❌ 不好
- 你应该在执行文件操作之前检查路径是否存在
- 完成代码修改之后可以考虑运行测试

2. 提供具体的操作路径

markdown

# ✅ 好
## 部署流程
1. 运行 `bun run build` 构建项目
2. 检查 `dist/` 目录是否生成
3. 执行 `rsync -avz dist/ server:/var/www/app/`
4. 在 memory/ 中记录部署时间和版本号

# ❌ 不好
## 部署
帮用户部署代码到服务器。

3. 定义记忆策略

markdown

## 记忆规则
- 用户提到的技术偏好 → 写入 MEMORY.md
- 项目配置变更 → 写入当天的 memory/ 日志
- 重要决策及其理由 → 写入 MEMORY.md
- 临时调试信息 → 不需要记录

第 23 章：工具编排策略

23.1 工具策略设计原则

工具配置不是"给的越多越好"——每增加一个工具，就增加一份安全风险和 Token 开销。

最小权限原则

只开放智能体完成任务所需的最少工具集

示例对比：

json5

// ❌ 懒惰配置：全开
{
  tools: { profile: "full" }
}

// ✅ 精确配置：按需开放
{
  tools: {
    profile: "minimal",
    allow: ["web_search", "web_fetch", "memory_search", "memory_get"],
    deny: ["exec", "browser", "group:automation"]
  }
}

23.2 工具 Profile 选型指南

Profile	包含的工具	适用场景	Token 开销
`full`	所有内置工具	个人全能助手	最高
`coding`	fs + runtime + web	编码智能体	中等
`messaging`	消息 + 会话工具	纯通信智能体	较低
`minimal`	几乎无工具	只读/对话智能体	最低

23.3 工具组合模式

以下是经过验证的工具组合方案：

模式一：研究助手

json5

{
  tools: {
    profile: "minimal",
    allow: [
      "web_search",     // 搜索信息
      "web_fetch",      // 读取网页
      "memory_search",  // 搜索历史记忆
      "memory_get"      // 读取记忆文件
    ]
  }
}

特点：只读操作，不能修改任何文件或执行命令。适合信息收集和整理。

模式二：编码助手

json5

{
  tools: {
    profile: "coding",
    deny: ["browser", "message", "group:automation"]
  }
}

特点：可以读写文件、执行命令、搜索网络，但不能控制浏览器、发送跨渠道消息或管理自动化任务。

模式三：运维管家

json5

{
  tools: {
    profile: "full",
    deny: ["browser", "canvas"]
  },
  sandbox: {
    mode: "non-main",
    workspaceAccess: "rw"
  }
}

特点：几乎全部权限，但在非主会话中强制沙箱化。适合需要执行系统命令的运维场景。

模式四：安全问答机器人

json5

{
  tools: {
    profile: "minimal"
    // 没有任何额外工具
  },
  sandbox: {
    mode: "all",
    workspaceAccess: "none"
  }
}

特点：零工具、全沙箱。即使被提示词注入也无法执行任何操作。适合面向公众的问答场景。

23.4 工具与模型的适配

不同模型在工具调用上的表现差异显著：

模型等级	工具调用能力	适合的工具配置
旗舰模型（Opus/GPT-5.1）	优秀，复杂工具链	`full` / `coding`
标准模型（Sonnet/GPT-4o）	良好，常规工具	`coding` / 自定义
轻量模型（Haiku/Mini）	基础，简单工具	`minimal` / 单一工具

实践建议：如果你的智能体需要复杂的多步工具调用（如"搜索网页 → 读取内容 → 分析数据 → 写入文件"），请使用旗舰模型。轻量模型在长工具链中容易出错。

第 24 章：记忆策略与上下文管理

24.1 记忆策略设计

不同类型的智能体需要不同的记忆策略。核心问题是：什么信息值得跨会话保留？

策略一：无记忆模式

json5

{
  // 不使用 MEMORY.md
  // 不配置 memory/ 目录的自动写入
  session: {
    reset: { idleMinutes: 30 }  // 30 分钟空闲后重置
  }
}

适用：临时问答、一次性任务。每次对话都是独立的。

策略二：日志记忆模式

在 AGENTS.md 中配置：

markdown

## 记忆规则
- 每次对话结束前，将关键信息记录到 memory/YYYY-MM-DD.md
- 不需要记录日常闲聊
- 记录格式：时间 + 主题 + 关键内容

适用：项目助手、工作机器人。需要按天追踪进展。

策略三：长期+日志双层模式

markdown

## 记忆规则

### 长期记忆（MEMORY.md）
- 用户的技术偏好和工作习惯
- 重大决策及其理由
- 项目架构和关键约定

### 日志记忆（memory/YYYY-MM-DD.md）
- 当天的任务进展
- 临时上下文信息
- 待办事项和提醒

适用：个人助手、长期合作的项目智能体。

24.2 上下文窗口管理

智能体的"记忆"受限于模型的上下文窗口。当对话过长时，必须在保留重要信息和控制 Token 成本之间权衡。

上下文预算分配

一个合理的上下文预算分配：

总上下文窗口（如 200K Token）
├── 系统提示          ≈ 5-15%     （工具描述、技能列表、Bootstrap 文件）
├── 对话历史          ≈ 60-75%    （用户消息 + 助手回复 + 工具结果）
└── 安全余量          ≈ 15-25%    （留给模型生成回复）

优化策略

1. 精简 Bootstrap 文件

每个 Bootstrap 文件都占用系统提示空间。避免在 AGENTS.md 或 SOUL.md 中塞入大量内容：

markdown

# ❌ 不好：AGENTS.md 写了 5000 字的详细指南
# ✅ 好：AGENTS.md 控制在 1000 字以内，详细指南放在技能文件中按需加载

2. 配置会话修剪

json5

{
  session: {
    pruning: {
      mode: "cache-ttl",
      ttlMinutes: 5
    }
  }
}

3. 定期压缩长对话

在 AGENTS.md 中添加规则：

markdown

## 会话管理
- 当对话超过 30 轮时，主动建议用户执行 /compact
- 压缩前确保所有重要信息已写入 memory/

24.3 跨会话信息传递

新会话不会继承旧会话的对话内容，但可以通过以下机制传递信息：

旧会话
  ↓ 写入 memory/YYYY-MM-DD.md 或 MEMORY.md
磁盘文件
  ↓ 新会话启动时自动加载今天和昨天的日志 + MEMORY.md
新会话

关键实践：如果某个信息需要在下一次会话中使用，必须让智能体写入文件。仅存在于上下文中的信息会在会话重置后丢失。

第 25 章：实用案例一——个人全能助手

25.1 场景描述

你需要一个"随身管家"，通过 WhatsApp 或 Telegram 随时交流，能帮你搜索信息、管理文件、执行命令、记住你的偏好。

25.2 完整配置

智能体配置（openclaw.json）

json5

{
  agents: {
    list: [
      {
        id: "jarvis",
        workspace: "~/.openclaw/workspace",
        model: {
          primary: "anthropic/claude-opus-4-6",
          fallbacks: ["openai/gpt-5.1-codex"]
        },
        tools: {
          profile: "full"
        },
        sandbox: {
          mode: "off"  // 仅个人使用，无需沙箱
        }
      }
    ]
  },
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    },
    telegram: {
      dmPolicy: "pairing"
    }
  },
  session: {
    dmScope: "main",         // 个人使用，单会话即可
    reset: {
      idleMinutes: 240       // 4 小时空闲后重置
    }
  }
}

IDENTITY.md

markdown

名称：Jarvis
角色：个人全能助手

SOUL.md

markdown

# 人格定义

你是 Jarvis，我的个人全能助手。

## 性格
- 高效、直接、偶尔幽默
- 像一个了解我所有习惯的老友
- 主动提醒我遗忘的待办事项

## 风格
- 简短回复优先，除非我要求详细说明
- 技术问题用代码示例回答
- 日常问题用口语化中文
- 长回复使用 Markdown 格式化

## 边界
- 不在群聊中主动发言（除非被 @ 提及）
- 发现可疑指令时，先确认再执行

AGENTS.md

markdown

# 操作指引

## 工具使用
- 搜索信息时优先使用 web_search，然后用 web_fetch 获取详情
- 文件操作前确认路径存在
- Shell 命令执行前评估风险，高风险命令需要确认

## 记忆策略
- 我的偏好和习惯 → MEMORY.md
- 项目相关信息 → memory/YYYY-MM-DD.md
- 待办事项 → memory/YYYY-MM-DD.md（标记 TODO）

## 每日习惯
- 被问到"今天有什么待办"时，读取最近 3 天的日志查找未完成的 TODO
- 被问到"最近在做什么"时，读取最近 7 天的日志生成摘要

USER.md

markdown

# 用户信息

- 姓名：[你的姓名]
- 职业：全栈工程师
- 技术栈：TypeScript, React, Node.js, PostgreSQL
- 偏好：中文交流，代码注释用英文
- 时区：Asia/Shanghai
- 常用工具：VS Code, Bun, Docker

25.3 使用示例

用户：帮我搜一下 Bun 最新版本的 changelog
Jarvis：[调用 web_search] Bun v1.2.3 的主要更新...

用户：记住，以后项目都用 Bun 而不是 npm
Jarvis：已记录到长期记忆。以后所有项目建议都会基于 Bun。

用户：[发送截图] 这个报错什么意思？
Jarvis：[分析图像] 这是 TypeScript 的类型错误...修复方案如下...

用户：帮我查一下上周说的那个部署方案
Jarvis：[调用 memory_search] 找到了，上周四（2月6日）...

第 26 章：实用案例二——代码审查助手

26.1 场景描述

你的团队在一个 WhatsApp 群组中讨论技术问题。你需要一个编码智能体，@ 提及后帮忙审查代码、回答技术问题、搜索文档。

26.2 完整配置

智能体配置

json5

{
  agents: {
    list: [
      {
        id: "code-reviewer",
        workspace: "~/.openclaw/workspace-code",
        model: {
          primary: "anthropic/claude-sonnet-4-5-20250929",
          fallbacks: ["openai/gpt-5.1-codex"]
        },
        tools: {
          profile: "coding",
          deny: ["message", "group:automation", "canvas"]
        },
        groupChat: {
          historyLimit: 30,
          mentionPatterns: ["@?codebot", "@?代码助手"]
        }
      }
    ]
  },
  bindings: [
    {
      channel: "whatsapp",
      peer: "120363...@g.us",     // 技术讨论群组 JID
      agent: "code-reviewer"
    }
  ],
  channels: {
    whatsapp: {
      groups: {
        "120363...@g.us": {
          requireMention: true     // 必须 @ 提及才响应
        }
      }
    }
  }
}

SOUL.md

markdown

# 人格定义

你是一个代码审查助手，负责帮团队审查代码和回答技术问题。

## 审查风格
- 先确认理解了代码的意图，再指出问题
- 按优先级排列问题：安全 > 正确性 > 性能 > 风格
- 给出修复建议时附上代码示例
- 对好的代码给予肯定

## 回复规范
- 群聊中回复保持简洁（3-5 行）
- 需要详细分析时，用代码块格式化
- 不确定的问题标注 ⚠️，建议人工复核

## 边界
- 不修改生产环境的代码（只读建议）
- 涉及安全漏洞时，私聊通知相关人员而非在群里公开
- 不处理与代码无关的话题

AGENTS.md

markdown

# 操作指引

## 代码审查流程
1. 阅读用户提供的代码/diff
2. 识别语言和框架
3. 从安全性、正确性、性能、可读性四个维度审查
4. 用 Markdown 格式输出审查意见

## 输出格式

### 审查意见模板

🔍 代码审查

总评：[一句话总结]

问题列表：

🔴 [严重] ...
🟡 [建议] ...
🟢 [很好] ...

修复建议： [代码示例]


## 技术栈偏好
- TypeScript: 使用 strict 模式
- React: 函数组件 + Hooks
- API: RESTful，使用 zod 做参数校验
- 测试: vitest

26.3 群组交互示例

Alice：@代码助手 帮我看看这段代码有没有问题
[粘贴代码]

代码助手：
🔍 代码审查

**总评**：逻辑正确，但有一个潜在的 SQL 注入风险

**问题列表**：
1. 🔴 [安全] 第 12 行：直接拼接 SQL 字符串，存在注入风险
2. 🟡 [建议] 第 8 行：可以用 optional chaining 简化空值检查
3. 🟢 [很好] 错误处理逻辑清晰

**修复建议**：
使用参数化查询替代字符串拼接...

Bob：@代码助手 TypeScript 的 satisfies 关键字怎么用？

代码助手：
`satisfies` 用于在不改变推断类型的前提下验证表达式是否满足某个类型...
[代码示例]

第 27 章：实用案例三——定时汇报智能体

27.1 场景描述

你需要一个智能体每天定时执行任务：收集信息、生成报告、发送到指定渠道。这展示了 OpenClaw 的 Cron 定时任务和跨渠道消息能力。

27.2 完整配置

智能体配置

json5

{
  agents: {
    list: [
      {
        id: "reporter",
        workspace: "~/.openclaw/workspace-reporter",
        model: {
          primary: "anthropic/claude-sonnet-4-5-20250929"
        },
        tools: {
          profile: "minimal",
          allow: [
            "web_search",
            "web_fetch",
            "exec",
            "message",
            "memory_search",
            "memory_get",
            "cron"
          ]
        }
      }
    ]
  }
}

Cron 定时任务配置

json5

{
  cron: {
    jobs: [
      {
        id: "daily-report",
        schedule: "0 9 * * *",           // 每天早上 9 点
        agent: "reporter",
        task: "生成今日简报并发送。包括：1) 搜索 AI 领域最新新闻 2) 检查 GitHub 仓库的 PR 和 Issue 3) 读取昨天的待办事项 4) 生成摘要报告发送到 WhatsApp",
        deliver: {
          channel: "whatsapp",
          to: "+8613800001111"           // 发送到你的 WhatsApp
        }
      },
      {
        id: "weekly-digest",
        schedule: "0 18 * * 5",          // 每周五下午 6 点
        agent: "reporter",
        task: "生成本周工作总结。阅读本周所有 memory/ 日志，提取关键进展、待办事项和决策，生成结构化周报",
        deliver: {
          channel: "telegram",
          to: "chat-id-123"
        }
      }
    ]
  }
}

AGENTS.md

markdown

# 操作指引

## 日报生成流程
1. 搜索 AI/科技领域最新新闻（web_search）
2. 获取 2-3 篇重要文章的摘要（web_fetch）
3. 检查记忆文件中的待办事项（memory_search "TODO"）
4. 汇总为简报，格式如下：

### 日报格式

📰 今日简报 | YYYY-MM-DD

AI 动态

[新闻 1 标题]：一句话摘要
[新闻 2 标题]：一句话摘要

待办提醒

[ ] 未完成项 1
[ ] 未完成项 2

今日建议

[基于最近的工作模式给出一条建议]


## 周报生成流程
1. 读取本周所有日志（memory/YYYY-MM-DD.md）
2. 提取关键进展、决策和待办
3. 按项目分类汇总
4. 标注下周重点事项

27.3 输出示例

每天早上 9 点，你的 WhatsApp 会收到：

📰 今日简报 | 2026-02-14

## AI 动态
- Anthropic 发布 Claude 4.6：新增多模态推理能力，性能提升 40%
- Google DeepMind 论文：新的蛋白质折叠预测方法
- OpenAI 宣布 GPT-5.1 Codex 全面开放

## 待办提醒
- [ ] 完成用户认证模块重构（2月12日记录）
- [ ] 更新 API 文档（2月13日记录）

## 今日建议
本周连续三天在深夜工作，建议今天早点休息。周末前完成认证模块即可。

第 28 章：实用案例四——多渠道客服智能体

28.1 场景描述

你运营一个小型 SaaS 产品，需要在 WhatsApp 和 Telegram 上提供客户支持。不同渠道的客户使用不同的语言。

28.2 完整配置

智能体配置

json5

{
  agents: {
    list: [
      {
        id: "support-zh",
        workspace: "~/.openclaw/workspace-support-zh",
        model: {
          primary: "anthropic/claude-sonnet-4-5-20250929"
        },
        tools: {
          profile: "minimal",
          allow: ["web_fetch", "memory_search", "memory_get"]
        },
        sandbox: {
          mode: "all",
          workspaceAccess: "ro"    // 只读，防止客户注入修改文件
        }
      },
      {
        id: "support-en",
        workspace: "~/.openclaw/workspace-support-en",
        model: {
          primary: "anthropic/claude-sonnet-4-5-20250929"
        },
        tools: {
          profile: "minimal",
          allow: ["web_fetch", "memory_search", "memory_get"]
        },
        sandbox: {
          mode: "all",
          workspaceAccess: "ro"
        }
      }
    ]
  },
  bindings: [
    // WhatsApp → 中文客服
    { channel: "whatsapp", agent: "support-zh" },
    // Telegram → 英文客服
    { channel: "telegram", agent: "support-en" }
  ],
  session: {
    dmScope: "per-channel-peer",   // 每个客户独立会话
    reset: {
      idleMinutes: 60              // 1 小时空闲后重置
    }
  },
  channels: {
    whatsapp: {
      dmPolicy: "open"             // 允许任何人联系
    },
    telegram: {
      dmPolicy: "open"
    }
  }
}

support-zh 的 SOUL.md

markdown

# 人格定义

你是 [产品名] 的中文客服助手。

## 核心职责
- 回答产品功能和使用方法的问题
- 帮助排查常见问题
- 收集用户反馈

## 风格
- 友好、耐心、专业
- 使用简体中文
- 复杂操作提供分步指引
- 主动询问是否还有其他问题

## 升级规则
- 涉及退款、计费问题 → 回复"我帮您转接人工客服"并记录到 memory/
- 涉及安全漏洞 → 立即记录并标记为紧急
- 无法回答的问题 → 诚实说明，承诺反馈

## 严格禁止
- 承诺未经确认的功能或时间表
- 泄露内部技术实现细节
- 讨论竞品的缺点

support-zh 的 AGENTS.md

markdown

# 操作指引

## 知识库
产品文档位于工作区的 `docs/` 目录。当用户提问时：
1. 先在 memory/ 中搜索是否有类似问题的解答
2. 在 docs/ 中查找相关文档
3. 如果都找不到，基于产品理解回答，并标注"此回答未经文档验证"

## 常见问题处理
- 登录问题 → 引导用户重置密码：docs/faq/login.md
- 支付问题 → 引导到支付页面，必要时升级
- 功能问题 → 查阅 docs/features/ 目录

## 记忆策略
- 每个客户的问题和解决方案 → memory/YYYY-MM-DD.md
- 反复出现的新问题 → MEMORY.md（供改进产品参考）

28.3 安全要点

面向公众的客服智能体安全要求更高：

风险	缓解措施
提示词注入	沙箱 + 只读工作区 + 最小工具集
信息泄露	不加载 MEMORY.md（群聊模式）
资源滥用	每会话隔离 + 空闲重置
恶意用户	渠道白名单或配对策略

第 29 章：实用案例五——团队协作多智能体

29.1 场景描述

一个三人技术团队，需要不同的智能体处理不同的工作流：一个负责编码，一个负责文档，一个负责项目管理。所有智能体共享一个 WhatsApp 技术群，但各有独立的私聊通道。

29.2 架构设计

                    ┌─────────────────┐
                    │   WhatsApp 群组  │
                    │  技术讨论群       │
                    └────────┬────────┘
                             │ 广播
              ┌──────────────┼──────────────┐
              ↓              ↓              ↓
     ┌────────────┐  ┌────────────┐  ┌────────────┐
     │  code-bot  │  │  doc-bot   │  │  pm-bot    │
     │  编码助手   │  │  文档助手   │  │  项目管理   │
     │  Opus 4.6  │  │  Sonnet 4.5│  │  Sonnet 4.5│
     └────────────┘  └────────────┘  └────────────┘

29.3 完整配置

json5

{
  agents: {
    list: [
      {
        id: "code-bot",
        workspace: "~/.openclaw/workspace-code",
        model: { primary: "anthropic/claude-opus-4-6" },
        tools: {
          profile: "coding",
          deny: ["group:automation"]
        },
        groupChat: {
          mentionPatterns: ["@?code-bot", "@?代码"]
        }
      },
      {
        id: "doc-bot",
        workspace: "~/.openclaw/workspace-doc",
        model: { primary: "anthropic/claude-sonnet-4-5-20250929" },
        tools: {
          profile: "minimal",
          allow: ["group:fs", "web_search", "web_fetch", "memory_search"]
        },
        groupChat: {
          mentionPatterns: ["@?doc-bot", "@?文档"]
        }
      },
      {
        id: "pm-bot",
        workspace: "~/.openclaw/workspace-pm",
        model: { primary: "anthropic/claude-sonnet-4-5-20250929" },
        tools: {
          profile: "minimal",
          allow: ["memory_search", "memory_get", "message"]
        },
        groupChat: {
          mentionPatterns: ["@?pm-bot", "@?PM"]
        }
      }
    ]
  },

  // 广播组：群组消息同时发给所有智能体
  broadcast: {
    "120363...@g.us": ["code-bot", "doc-bot", "pm-bot"]
  },

  // 私聊路由
  bindings: [
    // 开发者 Alice 的私聊 → code-bot
    { channel: "whatsapp", peer: "+8613800001111", agent: "code-bot" },
    // 技术写作 Bob → doc-bot
    { channel: "whatsapp", peer: "+8613800002222", agent: "doc-bot" },
    // 项目经理 Charlie → pm-bot
    { channel: "whatsapp", peer: "+8613800003333", agent: "pm-bot" }
  ],

  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+8613800001111", "+8613800002222", "+8613800003333"],
      groups: {
        "120363...@g.us": { requireMention: true }
      }
    }
  },

  session: {
    dmScope: "per-channel-peer"   // 每人独立会话
  }
}

29.4 群组协作交互

Alice：@代码 这个函数的时间复杂度是多少？
[粘贴代码]

code-bot：这段代码的时间复杂度是 O(n log n)，因为...

Bob：@文档 帮我查一下 React Server Components 的最新文档

doc-bot：根据官方文档...
[搜索并返回结果]

Charlie：@PM 这个迭代还有哪些未完成的任务？

pm-bot：根据记录，本迭代还有以下未完成项...

29.5 协作增强：子智能体委派

主协调智能体可以派遣子智能体执行专项任务：

json5

{
  id: "pm-bot",
  subagents: {
    allowAgents: ["code-bot", "doc-bot"],  // 允许委派给编码和文档智能体
    model: "anthropic/claude-sonnet-4-5-20250929",
    thinking: "low"
  }
}

使用场景：

Charlie：@PM 帮我做一个完整的技术调研，包括代码可行性分析和文档整理

pm-bot：好的，我同时启动两个子任务：
  1. 委派 code-bot 进行代码可行性分析
  2. 委派 doc-bot 进行文档整理

[sessions_spawn → code-bot]
[sessions_spawn → doc-bot]

结果会在完成后自动发给你。

第 30 章：实用案例六——自动化运维监控

30.1 场景描述

你需要一个智能体监控服务器状态，定期检查关键指标，发现异常时主动通知。

30.2 完整配置

智能体配置

json5

{
  agents: {
    list: [
      {
        id: "ops-bot",
        workspace: "~/.openclaw/workspace-ops",
        model: {
          primary: "anthropic/claude-sonnet-4-5-20250929"
        },
        tools: {
          profile: "minimal",
          allow: [
            "exec",             // 执行检查命令
            "message",          // 发送告警
            "web_fetch",        // 检查 API 状态
            "memory_search",
            "memory_get",
            "cron"
          ],
          elevated: {
            enabled: true,
            allowFrom: {
              whatsapp: ["+8613800001111"]  // 仅管理员可执行提权操作
            }
          }
        },
        sandbox: {
          mode: "non-main",     // 非主会话沙箱化
          workspaceAccess: "rw"
        }
      }
    ]
  }
}

Cron 定时检查任务

json5

{
  cron: {
    jobs: [
      {
        id: "health-check",
        schedule: "*/15 * * * *",        // 每 15 分钟
        agent: "ops-bot",
        task: "执行服务器健康检查：1) 运行 'df -h' 检查磁盘使用率 2) 运行 'free -m' 检查内存 3) curl 检查 API 端点 https://api.example.com/health 4) 如果任何指标异常（磁盘>85%, 内存>90%, API 返回非 200），发送告警到 WhatsApp",
        deliver: {
          channel: "whatsapp",
          to: "+8613800001111",
          onlyOnOutput: true             // 仅在有输出（异常）时发送
        }
      },
      {
        id: "daily-ops-report",
        schedule: "0 8 * * *",           // 每天早上 8 点
        agent: "ops-bot",
        task: "生成运维日报：汇总过去 24 小时的健康检查记录、异常事件和处理结果",
        deliver: {
          channel: "whatsapp",
          to: "+8613800001111"
        }
      }
    ]
  }
}

AGENTS.md

markdown

# 操作指引

## 健康检查流程
1. 检查磁盘使用率：`df -h`
   - 正常：< 85%
   - 警告：85-95%
   - 严重：> 95%

2. 检查内存：`free -m`
   - 正常：可用 > 10%
   - 警告：可用 5-10%
   - 严重：可用 < 5%

3. 检查 API 状态：`curl -s -o /dev/null -w "%{http_code}" https://api.example.com/health`
   - 正常：200
   - 异常：其他状态码或超时

## 告警格式

🚨 服务器告警 | YYYY-MM-DD HH:MM

级别：[🟡警告 / 🔴严重] 指标：[具体指标名] 当前值：[当前数值] 阈值：[正常阈值] 建议操作：[建议的处理方式]


## 告警规则
- 仅在发现异常时发送消息
- 同一类型的告警 1 小时内不重复发送（检查 memory/）
- 严重告警始终发送，无论是否重复

## 记忆策略
- 每次检查结果 → memory/YYYY-MM-DD.md
- 异常事件及处理方式 → MEMORY.md

30.3 告警输出示例

🚨 服务器告警 | 2026-02-14 14:30

级别：🟡 警告
指标：磁盘使用率（/dev/sda1）
当前值：87%
阈值：< 85%
建议操作：清理 /tmp 目录和旧日志文件。运行 `du -sh /var/log/*` 查看大文件。

小结

通过本部分的学习，你已经掌握了从零设计智能体到生产部署的完整流程。

核心设计原则回顾

原则	说明
最小权限	只开放必需的工具，不多给
明确人格	具体的 SOUL.md 产出更好的回复
显式记忆	重要信息必须写入文件，不依赖上下文
分层安全	身份控制 → 工具限制 → 沙箱隔离
按需复杂	从最简配置开始，逐步添加能力

六大案例速查

案例	核心能力	安全等级	适用场景
个人全能助手	全工具 + 全记忆	低（个人使用）	日常工作
代码审查助手	编码工具 + 群组门控	中等	团队协作
定时汇报智能体	Cron + 跨渠道消息	中等	自动化报告
多渠道客服	只读 + 沙箱	高（面向公众）	客户支持
团队协作多智能体	广播组 + 子智能体	中等	团队工作流
运维监控	Exec + Cron + 告警	中高	服务器运维

进阶方向

掌握基础案例后，你可以探索以下进阶主题：

技能开发：为智能体编写自定义技能，封装复杂工作流
Hook 自动化：通过事件驱动机制实现更精细的控制
浏览器自动化：结合 Browser 工具实现网页操作
多网关部署：跨服务器分布式智能体管理

实战检查清单

在构建你自己的智能体之前，确认以下要点：

设计阶段

[ ] 明确智能体的核心职责（它要解决什么问题？）
[ ] 选择合适的模型（旗舰 vs 标准 vs 轻量）
[ ] 确定工具策略（需要哪些工具？什么不需要？）
[ ] 设计记忆策略（什么信息需要跨会话保留？）

配置阶段

[ ] 编写具体的 SOUL.md（不是泛泛的"你是 AI 助手"）
[ ] 编写可操作的 AGENTS.md（包含明确的工作流和规则）
[ ] 配置安全策略（DM Policy + 沙箱 + 工具限制）
[ ] 测试会话重置和记忆保留

上线阶段

[ ] 运行 openclaw security audit 检查安全配置
[ ] 用测试消息验证路由和绑定是否正确
[ ] 确认记忆写入和读取正常工作
[ ] 设置告警和监控（如适用）

常见问题解答

Q1：我应该用一个全能智能体还是多个专用智能体？

A：遵循"单一职责原则"——如果一个智能体需要在完全不同的场景中表现出不同的行为（如编码 vs 客服），使用多个专用智能体更好。理由：

工具策略可以更精确（最小权限）
人格定义更一致
安全隔离更彻底
Token 开销更低（不需要加载不相关的工具描述）

Q2：智能体在群聊中总是回复不相关的消息怎么办？

A：确保配置了 requireMention: true，并在 SOUL.md 中明确指示：

markdown

## 群聊规则
- 只回应直接 @ 提及你的消息
- 与你无关的对话返回空回复

Q3：如何让智能体在不同时段使用不同模型？

A：使用 Cron + 配置热更新，或为不同时段创建不同的智能体：

json5

// 白天使用高性能模型
{ id: "day-bot", model: { primary: "anthropic/claude-opus-4-6" } }
// 夜间使用低成本模型
{ id: "night-bot", model: { primary: "minimax/MiniMax-M2.1" } }

然后通过定时任务切换路由绑定。

Q4：多个智能体之间如何共享知识？

A：三种方式：

共享只读目录：通过沙箱的 docker.binds 挂载相同的知识库目录
子智能体委派：一个智能体通过 sessions_spawn 调用另一个
会话消息：通过 sessions_send 直接通信

Q5：智能体的 Token 成本如何控制？

A：从最影响成本的因素入手：

选择合适的模型：轻量任务用小模型
精简工具集：每个工具描述占用 Token
控制 Bootstrap 文件大小：不超过 1000 字
启用会话修剪和压缩：减少上下文长度
合理的会话重置策略：避免无限增长的会话

参考文档：
concepts/agent — 智能体运行时详解
concepts/tools — 工具体系完整参考
concepts/memory — 记忆系统
concepts/security — 安全配置指南
guides/recipes — 更多智能体配方

第七部分：智能体（Agents）入门与实用案例 ​

第 22 章：从零设计一个智能体 ​

22.1 智能体设计思维框架 ​

22.2 最小可用智能体 ​

22.3 智能体设计清单 ​

身份与人格 ​

能力与权限 ​

记忆与上下文 ​

安全与访问 ​

22.4 人格设计的艺术 ​

反模式：模糊的人格定义 ​

正确做法：具体且有约束 ​

人格维度参考 ​

22.5 操作指引（AGENTS.md）的编写原则 ​

编写原则 ​

第 23 章：工具编排策略 ​

23.1 工具策略设计原则 ​

最小权限原则 ​

23.2 工具 Profile 选型指南 ​

23.3 工具组合模式 ​

模式一：研究助手 ​

模式二：编码助手 ​

模式三：运维管家 ​

模式四：安全问答机器人 ​

23.4 工具与模型的适配 ​

第 24 章：记忆策略与上下文管理 ​

24.1 记忆策略设计 ​

策略一：无记忆模式 ​

策略二：日志记忆模式 ​

策略三：长期+日志双层模式 ​

24.2 上下文窗口管理 ​

上下文预算分配 ​

优化策略 ​

24.3 跨会话信息传递 ​

第 25 章：实用案例一——个人全能助手 ​

25.1 场景描述 ​

25.2 完整配置 ​

智能体配置（openclaw.json） ​

IDENTITY.md ​

SOUL.md ​

AGENTS.md ​

USER.md ​

25.3 使用示例 ​

第 26 章：实用案例二——代码审查助手 ​

26.1 场景描述 ​

26.2 完整配置 ​

智能体配置 ​

SOUL.md ​

AGENTS.md ​

26.3 群组交互示例 ​

第 27 章：实用案例三——定时汇报智能体 ​

27.1 场景描述 ​

27.2 完整配置 ​

智能体配置 ​

Cron 定时任务配置 ​

AGENTS.md ​

AI 动态 ​

待办提醒 ​

今日建议 ​

27.3 输出示例 ​

第 28 章：实用案例四——多渠道客服智能体 ​

28.1 场景描述 ​

28.2 完整配置 ​

智能体配置 ​

support-zh 的 SOUL.md ​

support-zh 的 AGENTS.md ​

28.3 安全要点 ​

第 29 章：实用案例五——团队协作多智能体 ​

29.1 场景描述 ​

29.2 架构设计 ​

29.3 完整配置 ​

29.4 群组协作交互 ​

29.5 协作增强：子智能体委派 ​

第 30 章：实用案例六——自动化运维监控 ​

30.1 场景描述 ​

30.2 完整配置 ​

智能体配置 ​

Cron 定时检查任务 ​

AGENTS.md ​

30.3 告警输出示例 ​

第七部分：智能体（Agents）入门与实用案例

第 22 章：从零设计一个智能体

22.1 智能体设计思维框架

22.2 最小可用智能体

22.3 智能体设计清单

身份与人格

能力与权限

记忆与上下文

安全与访问

22.4 人格设计的艺术

反模式：模糊的人格定义

正确做法：具体且有约束

人格维度参考

22.5 操作指引（AGENTS.md）的编写原则

编写原则

第 23 章：工具编排策略

23.1 工具策略设计原则

最小权限原则

23.2 工具 Profile 选型指南

23.3 工具组合模式

模式一：研究助手

模式二：编码助手

模式三：运维管家

模式四：安全问答机器人

23.4 工具与模型的适配

第 24 章：记忆策略与上下文管理

24.1 记忆策略设计

策略一：无记忆模式

策略二：日志记忆模式

策略三：长期+日志双层模式

24.2 上下文窗口管理

上下文预算分配

优化策略

24.3 跨会话信息传递

第 25 章：实用案例一——个人全能助手

25.1 场景描述

25.2 完整配置

智能体配置（openclaw.json）

IDENTITY.md

SOUL.md

AGENTS.md

USER.md

25.3 使用示例

第 26 章：实用案例二——代码审查助手

26.1 场景描述

26.2 完整配置

智能体配置

SOUL.md

AGENTS.md

26.3 群组交互示例

第 27 章：实用案例三——定时汇报智能体

27.1 场景描述

27.2 完整配置

智能体配置

Cron 定时任务配置

AGENTS.md

AI 动态

待办提醒

今日建议

27.3 输出示例

第 28 章：实用案例四——多渠道客服智能体

28.1 场景描述

28.2 完整配置

智能体配置

support-zh 的 SOUL.md

support-zh 的 AGENTS.md

28.3 安全要点

第 29 章：实用案例五——团队协作多智能体

29.1 场景描述

29.2 架构设计

29.3 完整配置

29.4 群组协作交互

29.5 协作增强：子智能体委派

第 30 章：实用案例六——自动化运维监控

30.1 场景描述

30.2 完整配置

智能体配置

Cron 定时检查任务

AGENTS.md

30.3 告警输出示例