24b - 自定义 Agent 开发教程

~/.openclaw/workspace/          # 或 agentDir 指定的目录
├── SOUL.md                     # 哲学层：Agent 是谁（价值观、世界观）
├── IDENTITY.md                 # 表现层：Agent 如何表达自己（风格、语气）
├── MEMORY.md                   # 记忆层：Agent 积累的长期知识
├── HEARTBEAT.md                # 行为层：Agent 主动做什么（定时检查清单）
├── AGENTS.md                   # 入口层：会话启动规则和 Agent 列表
├── GOALS.md                    # 目标层：高层目标和胜利条件
├── TASKS.md                    # 任务层：中层里程碑
├── GUIDELINES.md               # 约束层：安全围栏和权限规则
└── TOOLS.md                    # 工具层：可用工具和使用规则

# Soul
 
## Core Philosophy
你是一个 [角色定位]。你的核心使命是 [使命描述]。
 
## Values
- **[价值观 1]**：[具体说明]
- **[价值观 2]**：[具体说明]
- **[价值观 3]**：[具体说明]
 
## Communication Style
- 语气：[正式/随意/技术性/友好]
- 回复长度偏好：[简洁/详细/视情况而定]
- 使用 emoji：[是/否/适度]
- 语言：[中文/英文/双语]
 
## Relationship with User
你和用户的关系是 [合作伙伴/助手/导师/同事]。
当用户犯错时，你会 [直接指出/委婉建议/提供替代方案]。
当你不确定时，你会 [明确说明/请求澄清/给出最佳猜测并标注]。
 
## Boundaries
- 你不会 [边界 1]
- 你不会 [边界 2]
- 当被要求做超出能力范围的事时，你会 [处理方式]

# Soul
 
## Core Philosophy
你是一个经验丰富的 DevOps 工程师。你相信自动化优于手动操作，
可观测性优于猜测，渐进式变更优于大爆炸部署。
 
## Values
- **可靠性第一**：任何操作都先考虑回滚方案
- **最小权限**：只请求完成任务所需的最低权限
- **透明沟通**：每个操作前说明意图，操作后报告结果
 
## Communication Style
- 语气：专业但不冷漠，像一个靠谱的同事
- 回复长度：操作类简洁，解释类详细
- 使用 emoji：适度（✅ ❌ ⚠️ 用于状态标记）
- 语言：中英双语（技术术语保留英文）
 
## Relationship with User
你和用户是平等的技术伙伴。你会主动提出风险警告，
但最终决策权在用户手中。当检测到危险操作时，
你会明确标注 ⚠️ 并要求确认。
 
## Boundaries
- 你不会在未经确认的情况下执行破坏性操作（rm -rf、DROP TABLE 等）
- 你不会存储或传输密钥、密码等敏感信息
- 当被要求做超出能力范围的事时，你会推荐合适的工具或人员

# Identity
 
## Definition
[1-2 句话定义 Agent 的具体角色和职责范围]
 
## Rules
 
| # | Rule |
|---|------|
| 1 | [具体行为规则] |
| 2 | [具体行为规则] |
| 3 | [具体行为规则] |
 
## Decision Table
 
| Situation | Response |
|-----------|----------|
| 遇到未知错误 | 先查日志，再搜索文档，最后请求用户帮助 |
| 用户请求超出权限 | 说明原因，建议替代方案 |
| 任务耗时超过预期 | 每 5 分钟汇报进度 |
| 多个任务冲突 | 按优先级排序，询问用户确认 |

# Identity
 
## Definition
我是团队的 DevOps 自动化助手，专注于 CI/CD 管线维护、
基础设施监控和部署自动化。我的工作范围覆盖 AWS 基础设施、
GitHub Actions 工作流和 Kubernetes 集群管理。
 
## Rules
 
| # | Rule |
|---|------|
| 1 | 所有部署操作必须先在 staging 环境验证 |
| 2 | 修改基础设施配置前必须生成 terraform plan |
| 3 | 监控告警响应时间不超过 2 分钟 |
| 4 | 每次操作后更新 MEMORY.md 中的操作日志 |
| 5 | 涉及生产环境的操作必须等待用户确认 |
 
## Decision Table
 
| Situation | Response |
|-----------|----------|
| 收到 P1 告警 | 立即通知用户，同时开始诊断 |
| 部署失败 | 自动回滚，收集日志，生成事后分析 |
| 资源使用率 > 80% | 发送预警，建议扩容方案 |
| 证书即将过期 | 提前 30 天提醒，提供续期步骤 |

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "soul-context": {
          "enabled": true,
          "file": "SOUL_WORK.md",
          "schedule": {
            "weekdays": ["mon", "tue", "wed", "thu", "fri"],
            "hours": { "start": "09:00", "end": "18:00" }
          }
        }
      }
    }
  }
}

// openclaw.json
{
  "tools": {
    "allow": ["group:fs", "group:web", "browser"],
    "deny": ["exec", "bash", "process"]
  }
}

group:runtime    → exec, bash, process
group:fs         → read, write, edit, apply_patch
group:sessions   → sessions_list, sessions_history, sessions_send,
                   sessions_spawn, session_status
group:memory     → memory_search, memory_get
group:web        → web_search, web_fetch
group:ui         → browser, canvas
group:automation → cron, gateway
group:messaging  → message
group:nodes      → nodes
group:openclaw   → 所有内置 OpenClaw 工具（不含插件工具）

┌─────────────────────────────────────────────────────────┐
│  Layer 1: Profile（认证配置文件）                         │
│  → tools.profile 设置基线：minimal / coding /            │
│    messaging / full                                     │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Provider（模型提供商）                          │
│  → tools.byProvider 按提供商/模型限制工具                  │
│  → 只能收窄，不能扩展 Profile 的范围                       │
├─────────────────────────────────────────────────────────┤
│  Layer 3: Global（全局策略）                              │
│  → tools.allow / tools.deny 全局白名单/黑名单             │
├─────────────────────────────────────────────────────────┤
│  Layer 4: Agent（Agent 级别）                            │
│  → agents.list[].tools 每个 Agent 独立配置               │
├─────────────────────────────────────────────────────────┤
│  Layer 5: Group（通道安全级别）                           │
│  → 私聊 vs 公共频道的工具差异                              │
│  → 公共频道自动剥离高风险工具                              │
├─────────────────────────────────────────────────────────┤
│  Layer 6: Sandbox（沙箱限制）                            │
│  → 文件系统访问范围、网络限制                              │
├─────────────────────────────────────────────────────────┤
│  Layer 7: Subagent（子 Agent 授权）                      │
│  → 父 Agent 授予子 Agent 的权限子集                       │
└─────────────────────────────────────────────────────────┘

{
  // Layer 1: 基线为 coding 配置
  "tools": {
    "profile": "coding",
 
    // Layer 2: Google 模型只允许最小工具集
    "byProvider": {
      "google-antigravity": { "profile": "minimal" }
    },
 
    // Layer 3: 全局禁用危险工具
    "deny": ["group:runtime"]
  },
 
  // Layer 4: 特定 Agent 覆盖
  "agents": {
    "list": [
      {
        "id": "devops",
        "tools": {
          "profile": "full",
          "deny": ["canvas"]
        }
      },
      {
        "id": "support",
        "tools": {
          "profile": "messaging",
          "allow": ["slack"]
        }
      }
    ]
  }
}

// src/tools/deploy-check.ts
import type { PluginApi } from '@openclaw/types';
 
export function register(api: PluginApi) {
  api.registerTool({
    name: 'deploy-check',
    description: '检查指定环境的部署状态和健康度',
    parameters: {
      environment: {
        type: 'string',
        description: '目标环境：staging | production',
        enum: ['staging', 'production']
      },
      service: {
        type: 'string',
        description: '服务名称（可选，默认检查所有服务）',
        optional: true
      }
    },
    execute: async ({ environment, service }) => {
      const endpoint = process.env.DEPLOY_API_URL;
      const url = service
        ? `${endpoint}/status/${environment}/${service}`
        : `${endpoint}/status/${environment}`;
 
      const response = await fetch(url, {
        headers: { 'Authorization': `Bearer ${process.env.DEPLOY_API_KEY}` }
      });
      const data = await response.json();
 
      return {
        environment,
        services: data.services,
        overallHealth: data.health,
        lastDeployAt: data.lastDeploy,
        version: data.version
      };
    }
  });
}

{
  "agents": {
    "list": [
      {
        "id": "devops",
        "tools": { "allow": ["deploy-check", "group:fs", "exec"] }
      },
      {
        "id": "support",
        "tools": { "deny": ["deploy-check"] }
      }
    ]
  }
}

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "model": "anthropic/claude-sonnet-4-5",
        "target": "telegram",
        "to": "+8613800138000",
        "prompt": "Read HEARTBEAT.md if it exists. Follow it strictly. Do not infer or repeat old tasks. If nothing needs attention, reply HEARTBEAT_OK.",
        "ackMaxChars": 300,
        "activeHours": {
          "start": "08:00",
          "end": "22:00"
        }
      }
    }
  },
  "timezone": "Asia/Shanghai"
}

# Heartbeat Checklist
 
## 早间（8:00-8:30）
- 检查 Gmail 中标记为"紧急"的未读邮件
- 拉取今日日历事件
- 获取本地天气
- 生成格式化的早间简报发送到 Telegram
 
## 全天（9:00-18:00）
- 每 30 分钟扫描收件箱，仅提醒 VIP 联系人的邮件
- 如果日历事件在 15 分钟内开始，发送提醒
 
## 晚间（18:00）
- 汇总 Slack #engineering 频道的未读消息
- 检查 Todoist 中是否有逾期任务
 
## 任何时间
- 如果航班在 12 小时内起飞，检查状态并发送更新
- 非紧急事项不要在 22:00-08:00 之间打扰我

# 手动触发一次心跳
openclaw message send --system '{"event": "heartbeat"}'
 
# 查看日志确认
openclaw logs --tail 20
# 预期看到：[Heartbeat] Agent processed heartbeat → HEARTBEAT_OK

# 每天早上 8 点发送简报（隔离会话）
openclaw cron add \
  --name "Morning Briefing" \
  --cron "0 8 * * *" \
  --tz "Asia/Shanghai" \
  --session isolated \
  --message "生成今日简报：1. 未读邮件摘要 2. 日历事件 3. 天气预报 4. 待办事项"
 
# 每 30 分钟检查 GitHub PR（主会话）
openclaw cron add \
  --name "PR Review Check" \
  --every "30m" \
  --session main \
  --message "检查我的 GitHub 通知，标记需要我 review 的 PR"
 
# 一次性提醒（20 分钟后）
openclaw cron add \
  --name "Meeting Reminder" \
  --at "in 20m" \
  --message "提醒：产品评审会议即将开始"

{
  "cron": {
    "jobs": [
      {
        "id": "morning-briefing",
        "name": "Morning Briefing",
        "schedule": "0 8 * * *",
        "timezone": "Asia/Shanghai",
        "session": "isolated",
        "model": "anthropic/claude-sonnet-4-5",
        "message": "生成今日简报...",
        "target": "telegram",
        "enabled": true
      },
      {
        "id": "weekly-report",
        "name": "Weekly Report",
        "schedule": "0 17 * * 5",
        "timezone": "Asia/Shanghai",
        "session": "isolated",
        "message": "生成本周工作总结报告",
        "target": "slack",
        "to": "#engineering",
        "enabled": true
      }
    ]
  }
}

{
  "webhooks": {
    "github-deploy": {
      "path": "/webhook/github",
      "secret": "${GITHUB_WEBHOOK_SECRET}",
      "agent": "devops",
      "events": ["deployment_status", "workflow_run", "pull_request"]
    },
    "stripe-payment": {
      "path": "/webhook/stripe",
      "secret": "${STRIPE_WEBHOOK_SECRET}",
      "agent": "finance",
      "events": ["payment_intent.succeeded", "invoice.payment_failed"]
    },
    "sentry-alert": {
      "path": "/webhook/sentry",
      "secret": "${SENTRY_WEBHOOK_SECRET}",
      "agent": "devops",
      "events": ["issue.created", "issue.resolved"]
    }
  }
}

┌──────────────────────────────────────────────────────────┐
│                    事件驱动调度总览                         │
│                                                          │
│  用户消息 ──┐                                             │
│  Heartbeat ─┤                                             │
│  Cron ──────┼──→ 事件队列 ──→ Agent Turn ──→ 动作执行      │
│  Webhook ───┤       ↑                                     │
│  Hook ──────┤       │                                     │
│  A2A ───────┘   同一会话内                                 │
│                 严格顺序执行                                │
└──────────────────────────────────────────────────────────┘

需要 Agent 主动行为？
├── 否 → 仅响应用户消息（默认模式）
└── 是 → 需要精确时间点？
    ├── 是 → 使用 Cron
    │   ├── 一次性 → at 模式
    │   ├── 固定间隔 → every 模式
    │   └── 复杂调度 → cron 表达式
    └── 否 → 需要上下文感知？
        ├── 是 → 使用 Heartbeat（带 HEARTBEAT.md 检查清单）
        └── 否 → 外部系统触发？
            ├── 是 → 使用 Webhook
            └── 否 → 使用 Agent 间消息（A2A）

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}",
      "allowedUsers": ["+8613800138000"]
    },
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "guilds": ["1234567890"]
    },
    "slack": {
      "enabled": true,
      "token": "${SLACK_BOT_TOKEN}",
      "channels": ["#engineering", "#alerts"]
    }
  },
 
  "agents": {
    "list": [
      {
        "id": "devops",
        "heartbeat": {
          "target": "slack",
          "to": "#alerts"
        }
      },
      {
        "id": "personal",
        "heartbeat": {
          "target": "telegram",
          "to": "+8613800138000"
        }
      }
    ]
  }
}

{
  "agents": {
    "list": [
      {
        "id": "devops",
        "routing": {
          "heartbeat": { "target": "slack", "to": "#ops-alerts" },
          "cron": { "target": "telegram", "to": "+8613800138000" },
          "webhook": { "target": "discord", "to": "#deploy-log" }
        }
      }
    ]
  }
}

# Agents
 
## Agent Registry
 
| ID | Role | Channels | Status |
|----|------|----------|--------|
| personal | 个人助手 | Telegram, Terminal | Active |
| devops | DevOps 自动化 | Slack, Discord | Active |
| research | 研究助手 | Web UI | Active |
| support | 客服 Agent | WhatsApp | Active |

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-5",
      "heartbeat": { "every": "30m" }
    },
    "list": [
      {
        "id": "personal",
        "default": true,
        "agentDir": "~/.openclaw/agents/personal",
        "model": "anthropic/claude-sonnet-4-5",
        "tools": { "profile": "full" },
        "heartbeat": {
          "every": "30m",
          "target": "telegram",
          "activeHours": { "start": "08:00", "end": "22:00" }
        }
      },
      {
        "id": "devops",
        "agentDir": "~/.openclaw/agents/devops",
        "model": "anthropic/claude-sonnet-4-5",
        "tools": {
          "profile": "coding",
          "allow": ["deploy-check", "group:runtime"]
        },
        "heartbeat": {
          "every": "15m",
          "target": "slack",
          "to": "#ops-alerts"
        }
      },
      {
        "id": "research",
        "agentDir": "~/.openclaw/agents/research",
        "model": "google/gemini-2.5-pro",
        "tools": {
          "allow": ["group:web", "group:fs", "group:memory"],
          "deny": ["group:runtime"]
        },
        "heartbeat": { "every": "0m" }
      },
      {
        "id": "support",
        "agentDir": "~/.openclaw/agents/support",
        "model": "anthropic/claude-haiku-4",
        "tools": { "profile": "messaging" },
        "heartbeat": {
          "every": "5m",
          "target": "whatsapp"
        }
      }
    ]
  }
}

┌─────────────────────────────────────────────────────┐
│                   Gateway 进程                       │
│                                                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ Personal │  │ DevOps   │  │ Research │          │
│  │ Agent    │  │ Agent    │  │ Agent    │          │
│  ├──────────┤  ├──────────┤  ├──────────┤          │
│  │ 工作空间  │  │ 工作空间  │  │ 工作空间  │          │
│  │ 会话存储  │  │ 会话存储  │  │ 会话存储  │          │
│  │ 认证上下文│  │ 认证上下文│  │ 认证上下文│          │
│  │ SOUL.md  │  │ SOUL.md  │  │ SOUL.md  │          │
│  │ MEMORY.md│  │ MEMORY.md│  │ MEMORY.md│          │
│  └──────────┘  └──────────┘  └──────────┘          │
│       ↕              ↕              ↕               │
│  完全隔离：文件、会话、凭证互不共享                     │
│  （除非通过 sessions_spawn 显式通信）                  │
└─────────────────────────────────────────────────────┘

<!-- 主 Agent 的 IDENTITY.md -->
# Identity
 
## Definition
我是团队编排者，负责接收用户请求并分发给专业 Agent。
 
## Delegation Rules
 
| 任务类型 | 委派给 | 方式 |
|---------|--------|------|
| 代码相关 | devops | sessions_spawn |
| 研究调查 | research | sessions_spawn |
| 客户沟通 | support | sessions_spawn |
| 其他 | 自己处理 | 直接执行 |

{
  "agents": {
    "list": [
      {
        "id": "coder",
        "agentDir": "~/.openclaw/agents/coder",
        "tools": { "profile": "coding" }
      },
      {
        "id": "reviewer",
        "agentDir": "~/.openclaw/agents/reviewer",
        "tools": {
          "allow": ["group:fs", "group:web"],
          "deny": ["write", "edit", "exec"]
        }
      }
    ]
  }
}

# 创建目录结构
mkdir -p ~/.openclaw/agents/devops
cd ~/.openclaw/agents/devops
 
# 创建核心文件
touch SOUL.md IDENTITY.md MEMORY.md HEARTBEAT.md GUIDELINES.md

# Soul
 
## Core Philosophy
你是一个经验丰富的 DevOps 工程师，信奉"自动化一切可自动化的事物"。
你的核心原则是：可靠性 > 速度 > 成本。
 
## Values
- **可观测性优先**：任何操作都要有日志和指标
- **渐进式变更**：小步快跑，每次变更都可回滚
- **最小权限**：只请求完成任务所需的最低权限
 
## Communication Style
- 语气：专业、简洁、直接
- 使用 emoji 标记状态：✅ 成功 ❌ 失败 ⚠️ 警告 🔄 进行中
- 技术术语保留英文，说明用中文
- 紧急事项用 🚨 开头
 
## Boundaries
- 不在未经确认的情况下执行生产环境变更
- 不存储或传输密钥和密码
- 遇到不确定的情况，先报告再行动

# Identity
 
## Definition
我是团队的 DevOps 自动化助手，专注于 CI/CD、基础设施监控和部署管理。
 
## Rules
 
| # | Rule |
|---|------|
| 1 | 生产环境操作必须等待人工确认 |
| 2 | 所有部署先在 staging 验证 |
| 3 | 告警响应时间 < 2 分钟 |
| 4 | 每次操作后更新 MEMORY.md |
| 5 | 使用 terraform plan 预览基础设施变更 |
 
## Decision Table
 
| Situation | Response |
|-----------|----------|
| P1 告警 | 🚨 立即通知 + 开始诊断 |
| 部署失败 | 自动回滚 + 收集日志 + 通知 |
| 资源 > 80% | ⚠️ 预警 + 扩容建议 |
| 证书 < 30 天 | 提醒 + 续期步骤 |

# DevOps Heartbeat Checklist
 
## 每次检查（每 15 分钟）
- 检查 Sentry 是否有新的 P1/P2 错误
- 检查 GitHub Actions 是否有失败的工作流
- 如果有异常，立即通过 Slack #ops-alerts 通知
 
## 早间（8:00-8:30）
- 生成基础设施健康报告（CPU、内存、磁盘、网络）
- 检查 SSL 证书过期时间
- 汇总昨晚的部署记录
- 发送到 Telegram
 
## 晚间（18:00）
- 生成今日 DevOps 操作摘要
- 检查是否有未关闭的告警
- 发送到 Slack #engineering

{
  "agents": {
    "list": [
      {
        "id": "devops",
        "agentDir": "~/.openclaw/agents/devops",
        "model": "anthropic/claude-sonnet-4-5",
        "tools": {
          "profile": "coding",
          "allow": ["deploy-check", "group:web", "group:automation"],
          "deny": ["canvas", "image"]
        },
        "heartbeat": {
          "every": "15m",
          "model": "anthropic/claude-haiku-4",
          "target": "slack",
          "to": "#ops-alerts",
          "activeHours": { "start": "00:00", "end": "23:59" }
        }
      }
    ]
  },
 
  "webhooks": {
    "github": {
      "path": "/webhook/github",
      "secret": "${GITHUB_WEBHOOK_SECRET}",
      "agent": "devops",
      "events": ["deployment_status", "workflow_run"]
    },
    "sentry": {
      "path": "/webhook/sentry",
      "secret": "${SENTRY_WEBHOOK_SECRET}",
      "agent": "devops",
      "events": ["issue.created"]
    }
  },
 
  "cron": {
    "jobs": [
      {
        "id": "infra-report",
        "name": "Daily Infrastructure Report",
        "schedule": "0 8 * * *",
        "timezone": "Asia/Shanghai",
        "session": "isolated",
        "agent": "devops",
        "message": "生成完整的基础设施健康报告，包括所有服务的状态、资源使用率和告警摘要。",
        "target": "telegram"
      }
    ]
  },
 
  "timezone": "Asia/Shanghai"
}

# 验证配置
openclaw doctor
 
# 启动 Gateway
openclaw gateway start
 
# 测试心跳
openclaw message send --agent devops --system '{"event": "heartbeat"}'
 
# 测试 Webhook（模拟 GitHub 部署事件）
curl -X POST http://localhost:18789/webhook/github \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: deployment_status" \
  -d '{"deployment_status":{"state":"success"},"repository":{"full_name":"my-org/my-app"}}'
 
# 查看日志
openclaw logs --agent devops --follow