Files

scott 6d3b50cebc docs: 添加 OpenClaw 多 Agent 配置方案 v2/v3

v2 基于原始需求优化（精简 Skills、通信协议、部署审批、版本锁定）。
v3 基于本机实际环境检查修正（路径、Agent 数量、Skills 可用性等）。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-19 12:51:37 +08:00

35 KiB

Raw Blame History

name, overview, todos, isProject

name

overview

todos

isProject

OpenClaw Agent Configuration v3

基于本机实际 OpenClaw 环境检查结果修正的配置方案。在现有 1 个 main Agent + 1 个飞书应用的基础上，增量添加 4 个积分商城 Agent，不影响已有配置。

id	content	status
create-feishu-apps	在飞书开放平台创建 4 个机器人应用（或复用现有应用做路由）	pending

id	content	status
update-openclaw-json	在现有 openclaw.json 中追加 4 个 Agent、bindings 和飞书账号	pending

id	content	status
create-workspaces	创建 4 个 Agent workspace 目录和全套 .md 文件	pending

id	content	status
install-skills	安装本地 Skills 和 ClawHub Skills	pending

id	content	status
register-and-verify	运行 openclaw doctor 验证配置	pending

false

OpenClaw 多 Agent 配置方案 v3 -- 单商户积分商城

v3 核心变更（基于实际环境检查）：

v1/v2 方案假设已有 6 个 Agent、4 个飞书账号、多个本地 Skills 等，与实际环境严重不符。 v3 基于 2026-03-19 对 /Users/mac/.openclaw/ 的实际检查结果重写。

一、实际环境检查结果

1.1 与 v1/v2 假设的差异对照

项目	v1/v2 假设	实际情况
macOS 用户目录	`/Users/apple/`	`/Users/mac/`
已有 Agent	6 个（main, miao, msh, jxy, mom, my-production）	仅 1 个（main）
已有飞书账号	4 个（default, msh, jxy, mom）	仅 1 个（default）
已有 binding	4 条	仅 1 条（main → feishu:default）
本地 Skills	13 个已安装	0 个（无 skills 目录）
已安装 plugins	feishu, acpx, maven-connector, minimax-portal-auth	仅 feishu
模型 provider	minimax-portal, kimi-coding 等多个	仅 moonshot + kimi-coding（共用同一 API key）
workspace	多个独立 workspace 目录	1 个共享 workspace（模板状态，未自定义）
默认模型	minimax-portal/MiniMax-M2.5	kimi-coding/k2p5
OpenClaw 版本	未指定	2026.3.13
飞书连接方式	未指定	websocket

1.2 实际配置详情

~/.openclaw/
├── openclaw.json          # 主配置文件
├── openclaw.json.bak      # 自动备份（共 3 份）
├── agents/
│   └── main/              # 唯一的 Agent
│       ├── agent/         # models.json, auth-profiles.json
│       └── sessions/      # 会话记录
├── workspace/             # 共享 workspace（默认模板状态）
│   ├── IDENTITY.md        # 未填写
│   ├── SOUL.md            # 默认模板
│   ├── AGENTS.md          # 默认模板
│   ├── TOOLS.md           # 默认模板
│   ├── USER.md            # 未填写
│   ├── BOOTSTRAP.md       # 仍存在（说明未完成初始化引导）
│   └── HEARTBEAT.md       # 空（无定时任务）
├── extensions/
│   └── feishu/            # 飞书插件（含 feishu-doc/drive/perm/wiki 4 个 skill）
├── memory/
│   └── main.sqlite        # 记忆数据库
├── cron/
│   └── jobs.json          # 空
├── feishu/
│   └── dedup/             # 飞书消息去重
├── completions/           # shell 补全脚本
├── canvas/                # Web UI
├── devices/               # 设备信息
├── identity/              # 设备认证
└── logs/                  # 日志

模型配置：

moonshot：Kimi K2.5（OpenAI 兼容 API），256K 上下文，非推理模型
kimi-coding：Kimi for Coding / k2p5（Anthropic 兼容 API），262K 上下文，推理模型
两个 provider 共用同一 API key
默认模型：kimi-coding/k2p5

飞书配置：

1 个应用：cli_a930893990799cba
连接模式：websocket
策略：groupPolicy=open, dmPolicy=open, allowFrom=*

Gateway：

端口 18789，local 模式，loopback 绑定，token 鉴权

二、Agent 角色设计（4 个）

与 v2 保持一致，不再赘述。

flowchart TB
    User[用户/飞书] -->|提需求| PM["integral-pm (PM + 设计)"]
    PM -->|后端任务 + API 设计| BE[integral-backend]
    PM -->|前端任务 + UI 规范| FE["integral-frontend (管理后台 + 用户端)"]
    PM -->|测试计划| QA["integral-qa (测试 + 部署验证)"]
    BE -->|API 就绪| FE
    BE -->|提测| QA
    FE -->|提测| QA
    QA -->|Bug 反馈| BE
    QA -->|Bug 反馈| FE
    QA -->|测试报告| PM
    QA -.->|部署申请| PM
    PM -.->|部署审批| QA

Agent ID	角色	职责范围
integral-pm	项目经理 + 设计	需求拆解、PRD、UI 设计规范、任务分派、进度跟踪、部署审批
integral-backend	后端开发	Java/Spring Boot 接口开发、数据库变更、API 文档
integral-frontend	前端开发	管理后台 Vue + 用户端 uni-app 开发
integral-qa	测试 + 部署	测试用例、功能测试、回归测试、部署执行（需 PM 审批）

三、Agent 间通信协议

3.1 通信方式

由于当前飞书只有 1 个应用，Agent 间通信有两种选择：

方案 A（推荐）：共享飞书群 + @mention 路由

创建一个飞书群「积分商城-协作」，所有 Agent 加入。通过消息中 @Agent名 或 /命令前缀 触发对应 Agent。

方案 B：4 个独立飞书应用

在飞书开放平台新建 4 个机器人应用，各自独立 appId/appSecret。私聊直达对应 Agent。

v3 以方案 B 为主方案（更可靠），方案 A 作为降低运维成本的备选。原因：OpenClaw 的 binding 路由目前以 accountId 为主要匹配字段，keyword 路由是否支持需验证。

3.2 消息协议格式

所有 Agent 间通信遵循统一格式：

【<消息类型>】<标题>
发送方: <agent-id>
接收方: @<target-agent>
关联任务: <task-id>
---
<消息正文>

消息类型：任务分派、API-就绪、提测通知、Bug-反馈、测试报告、部署申请、部署审批、进度更新。

3.3 任务状态机

Created → InProgress → CodeReview → Testing → Passed → DeployApproval → Deploying → Done
                                      ↓                      ↓
                                   BugFound ← ─ ─ ─ ─ ─ ─ ─ ┘
                                      ↓
                                  InProgress（修复后重新流转）

四、openclaw.json 增量修改

原则：只追加，不修改已有配置。 当前 openclaw.json 中仅有 1 个 main Agent 和 1 条 binding，以下为增量部分。

4.1 在 `agents.list` 中追加 4 个 Agent

当前 agents 节点只有 defaults，没有 list 数组。需要新增 list 字段：

"agents": {
  "defaults": {
    ... // 保持不变
  },
  "list": [
    {
      "id": "integral-pm",
      "name": "integral-pm",
      "workspace": "/Users/mac/.openclaw/workspace-integral-pm",
      "agentDir": "/Users/mac/.openclaw/agents/integral-pm/agent",
      "model": "kimi-coding/k2p5"
    },
    {
      "id": "integral-backend",
      "name": "integral-backend",
      "workspace": "/Users/mac/.openclaw/workspace-integral-backend",
      "agentDir": "/Users/mac/.openclaw/agents/integral-backend/agent",
      "model": "kimi-coding/k2p5"
    },
    {
      "id": "integral-frontend",
      "name": "integral-frontend",
      "workspace": "/Users/mac/.openclaw/workspace-integral-frontend",
      "agentDir": "/Users/mac/.openclaw/agents/integral-frontend/agent",
      "model": "kimi-coding/k2p5"
    },
    {
      "id": "integral-qa",
      "name": "integral-qa",
      "workspace": "/Users/mac/.openclaw/workspace-integral-qa",
      "agentDir": "/Users/mac/.openclaw/agents/integral-qa/agent",
      "model": "kimi-coding/k2p5"
    }
  ]
}

路径修正： 所有路径以 /Users/mac/ 为基础，非 v1 中的 /Users/apple/。

4.2 在 `bindings` 数组中追加 4 条飞书路由

当前只有 1 条 binding（main → feishu:default）。在其后追加：

"bindings": [
  {
    "agentId": "main",
    "match": {
      "channel": "feishu",
      "accountId": "default"
    }
  },
  {
    "agentId": "integral-pm",
    "match": {
      "channel": "feishu",
      "accountId": "integral-pm"
    }
  },
  {
    "agentId": "integral-backend",
    "match": {
      "channel": "feishu",
      "accountId": "integral-backend"
    }
  },
  {
    "agentId": "integral-frontend",
    "match": {
      "channel": "feishu",
      "accountId": "integral-frontend"
    }
  },
  {
    "agentId": "integral-qa",
    "match": {
      "channel": "feishu",
      "accountId": "integral-qa"
    }
  }
]

4.3 在 `channels.feishu` 中追加 `accounts`

当前飞书配置是单应用模式（appId/appSecret 在根级）。需要追加 accounts 字段支持多应用：

"channels": {
  "feishu": {
    "enabled": true,
    "appId": "cli_a930893990799cba",
    "appSecret": "FfpFz93MKBx0ytC1ceTPF0BnjM7vFVhQ",
    "connectionMode": "websocket",
    "domain": "feishu",
    "groupPolicy": "open",
    "dmPolicy": "open",
    "allowFrom": ["*"],
    "accounts": {
      "integral-pm": {
        "appId": "<飞书开放平台创建后填入>",
        "appSecret": "<飞书开放平台创建后填入>",
        "agent": "integral-pm",
        "dmPolicy": "open",
        "allowFrom": ["*"]
      },
      "integral-backend": {
        "appId": "<飞书开放平台创建后填入>",
        "appSecret": "<飞书开放平台创建后填入>",
        "agent": "integral-backend",
        "dmPolicy": "open",
        "allowFrom": ["*"]
      },
      "integral-frontend": {
        "appId": "<飞书开放平台创建后填入>",
        "appSecret": "<飞书开放平台创建后填入>",
        "agent": "integral-frontend",
        "dmPolicy": "open",
        "allowFrom": ["*"]
      },
      "integral-qa": {
        "appId": "<飞书开放平台创建后填入>",
        "appSecret": "<飞书开放平台创建后填入>",
        "agent": "integral-qa",
        "dmPolicy": "open",
        "allowFrom": ["*"]
      }
    }
  }
}

注意： 根级 appId/appSecret（cli_a930893990799cba）保持不变，这是 main Agent 使用的默认应用。新增的 4 个账号各自独立。

4.4 不变动的部分

meta、wizard — 系统自动管理
auth — 保持现有 2 个 profile（moonshot:default, kimi-coding:default）
models — 保持现有 2 个 provider（moonshot, kimi-coding）
tools — 保持 web search 配置
commands、session — 保持现有配置
gateway — 端口 18789，鉴权 token 不变
plugins — 仅 feishu，保持不变
main Agent 的 binding — 保持不变

五、双模型架构

当前环境只有 2 个模型 provider，都使用 Kimi API。Cursor CLI 作为第二层编码工具：

层	用途	Agent	模型
OpenClaw	飞书对话、任务协调	全部	kimi-coding/k2p5（已有，无需新增）
Cursor	代码编写、项目修改	PM	`agent --model claude-4.6-opus`
Cursor	代码编写、项目修改	BE/FE/QA	`agent --model auto`

前提： Cursor IDE 已在本机安装并可通过 CLI 调用。若 Cursor 未安装，需先安装。

六、Skills 配置（基于实际情况修正）

6.1 实际可用资源盘点

当前无任何本地 Skills。v1/v2 中提到的 gitea-version-control、maven-helper、spring-boot-engineer 等 13 个 skill 均不存在，需要从头安装或创建。

已有的 skill 仅限飞书插件自带的 4 个：feishu-doc、feishu-drive、feishu-perm、feishu-wiki。

6.2 Skills 安装计划

分三个阶段，从最小可用集开始：

阶段一：最小启动集（Day 1）

仅使用 OpenClaw 内置 Tools，不安装任何额外 Skill：

内置 Tool	integral-pm	integral-backend	integral-frontend	integral-qa
git	●	●	●	●
file-manager	●	●	●	●
web-search	●	●	●	●
browser	●	-	●	●
code-runner	-	●	●	●
http-request	-	●	-	●
合计	4	5	5	6

此阶段目标：验证 Agent 注册、飞书路由、基本对话功能正常。

阶段二：核心 Skills 安装（Day 2-3）

从 ClawHub 安装或本地创建以下 Skill：

Skill	来源	适用 Agent	安装命令 / 创建方式
cursor-cli	需自行创建	全部	自定义 skill，封装 Cursor CLI 调用
gitea-tools	需自行创建	全部	自定义 skill，封装 Gitea API 操作

关键变更： v1/v2 中列出的 gitea-version-control、maven-helper、spring-boot-engineer 等 Skill 在本机并不存在。需要确认是否有 ClawHub 可安装版本，或者需要自行创建。

# 先搜索 ClawHub 是否有可用 Skill
openclaw skills search gitea
openclaw skills search maven
openclaw skills search spring-boot
openclaw skills search cursor
openclaw skills search frontend-design

阶段三：进阶 Skills（Week 2+）

根据阶段一二的运行情况，按需引入：

代码审查 Skill（如 ClawHub 有 code-reviewer）
自动化测试 Skill（UI 自动化）
摘要 Skill（测试报告生成）

6.3 最终目标分配矩阵（阶段二完成后）

Skill / Tool	integral-pm	integral-backend	integral-frontend	integral-qa
git	●	●	●	●
file-manager	●	●	●	●
web-search	●	●	●	●
browser	●	-	●	●
code-runner	-	●	●	●
http-request	-	●	-	●
cursor-cli	● (opus)	● (auto)	● (auto)	● (auto)
gitea-tools	●	●	●	●
合计	6	7	7	8

七、各 Agent Workspace 配置

7.1 项目路径确认

待确认： v1/v2 中的项目路径为 /Users/apple/scott2026/integral-shop/single-shop-22。由于本机用户为 /Users/mac/，实际项目路径需要确认。以下使用占位符 <PROJECT_ROOT> 表示。

7.2 统一目录结构

~/.openclaw/workspace-integral-<role>/
  IDENTITY.md
  SOUL.md
  AGENTS.md
  USER.md
  TOOLS.md
  HEARTBEAT.md
  memory/
  plans/
  tasks/

1. PM Agent (integral-pm)

workspace 路径： /Users/mac/.openclaw/workspace-integral-pm/

IDENTITY.md:

# IDENTITY.md

- **Name:** 积分商城PM
- **Creature:** AI 项目经理
- **Vibe:** 结构化、专业、高效
- **Emoji:** 📋

SOUL.md:

# SOUL.md - 积分商城 PM

## 角色定义
项目经理兼 UI 设计指导。负责需求拆解、任务分派、进度跟踪、部署审批。

## 沟通风格
- 结构化、简洁、中文为主
- 任务分派使用标准消息协议格式
- 不说废话，直接给结论和下一步行动

## 决策原则
- MVP 优先、增量迭代
- 技术方案交由开发 Agent 决定，PM 不干预实现细节
- 部署审批必须确认：测试通过率 ≥ 95%、无 P0 Bug

## 设计输出
以文字描述 + 参考截图形式交付 UI 规范，不做独立设计稿。
管理后台遵循 Element UI 2.13 风格，用户端遵循现有积分商城 H5 风格。

## 禁止行为
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md

AGENTS.md:

# AGENTS.md - PM 工作规范

## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）
4. Read plans/ 下最新的 PRD

## 工作流
1. 收到需求 → 写 PRD 到 plans/<feature>.md
2. 拆解为子任务 → 写入 tasks/<YYYY-MM-DD>-<feature>-<subtask>.md
3. 通过飞书分别通知 integral-backend / integral-frontend / integral-qa

## 任务文件格式

优先级: P0/P1/P2
状态: Created/InProgress/Testing/Passed/Deploying/Done
验收标准（AC）
依赖关系
负责 Agent


## 通信协议
所有 Agent 间消息格式：

【<消息类型>】<标题> 发送方: integral-pm 接收方: @ 关联任务:

<消息正文>


消息类型: 任务分派 / API-就绪 / 提测通知 / Bug-反馈 / 测试报告 / 部署申请 / 部署审批 / 进度更新

## 部署审批流程
1. 收到 QA 的【部署申请】
2. 检查：测试报告通过率 ≥ 95%、无 P0 Bug
3. 测试环境（by80）/ 预发布环境（miao33）: 直接批准
4. 生产环境（miao50）: 需 @用户 人工确认后批准
5. 回复【部署审批】消息

## Cursor 使用
- agent --model claude-4.6-opus
- 用途: 需求分析、代码审阅、架构设计

## Memory
- 每日进度汇总到 memory/YYYY-MM-DD.md

TOOLS.md:

# TOOLS.md - PM 环境信息

## 项目信息
- 源码路径: <PROJECT_ROOT>
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git
- 编码工具: Cursor IDE (macOS)

## 子项目结构
- backend/              → Java Spring Boot 后端
- backend-adminend/     → 管理后台 Vue 前端
- single_uniapp22miao/  → 用户端 uni-app H5

## Cursor CLI
- 模型: agent --model claude-4.6-opus
- 项目目录: <PROJECT_ROOT>

## 已启用 Tools
- 内置: git, file-manager, web-search, browser

2. Backend Agent (integral-backend)

workspace 路径： /Users/mac/.openclaw/workspace-integral-backend/

IDENTITY.md:

# IDENTITY.md

- **Name:** 后端开发
- **Creature:** AI 后端工程师
- **Vibe:** 技术精确、严谨
- **Emoji:** ⚙️

SOUL.md:

# SOUL.md - 后端开发

## 角色定义
Java 后端开发工程师，负责积分商城后端接口开发。

## 技术栈版本锁定（严格遵守，禁止升级）
- **Java: 1.8**（禁止使用 var、Records、模块化等 Java 9+ 特性）
- **Spring Boot: 2.2.6.RELEASE**（禁止使用 Spring Boot 3.x API）
- **MyBatis Plus: 3.3.1**
- **MySQL: 5.7**（禁止使用窗口函数、CTE 等 MySQL 8.0 特性）
- **Maven: 3.6.1**
- **Redis: 5.x 兼容 API**

## 编码规范
- 阿里 Java 开发规约
- RESTful API 设计
- 接口变更须提供 Swagger 注解并说明影响范围

## 沟通风格
技术精确。变更通知包含：变更接口列表、请求/响应格式变化、影响的前端页面。

## 禁止行为
- 禁止引入新的 Maven 依赖（除非 PM 明确批准）
- 禁止修改 pom.xml 中已有依赖的版本号
- 禁止修改 application.yml 中的端口和数据库配置
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md

AGENTS.md:

# AGENTS.md - 后端开发工作规范

## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）

## 代码范围
<PROJECT_ROOT>/backend/

## 模块结构
- crmeb-admin:   管理后台 API
- crmeb-front:   用户端 API
- crmeb-service: 业务逻辑
- crmeb-common:  公共模块

## 开发流程
1. 从 PM 任务获取需求
2. 在 develop 基础上创建 feature/backend-<name> 分支
3. 在 Cursor 中编码: agent --model auto
4. 新增接口须同步更新 Swagger 注解
5. 数据库变更 → backend/sql/<YYYY-MM-DD>-<description>.sql
6. 本地构建验证: mvn clean compile -pl <module> -am
7. Push 到 Gitea
8. 飞书通知 @integral-frontend【API-就绪】
9. 飞书通知 @integral-qa【提测通知】

## 通信协议
遵循 PM 定义的标准消息格式。

## 故障恢复
- Cursor CLI 失败: git stash → 记录 memory/errors.md → 通知 PM
- 构建失败: 分析日志 → 尝试修复 → 3 次失败后上报 PM

TOOLS.md:

# TOOLS.md - 后端开发环境

## 开发环境 (macOS)
- Java: 1.8
- Maven: 3.6.1
- IDE: Cursor
- 项目路径: <PROJECT_ROOT>/backend

## 本地运行
- Admin API: mvn spring-boot:run -pl crmeb-admin (端口 8080)
- Front API: mvn spring-boot:run -pl crmeb-front (端口 8081)

## 打包
- Admin: mvn clean package -pl crmeb-admin -am -DskipTests
- Front: mvn clean package -pl crmeb-front -am -DskipTests

## 版本管理
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git
- 分支规范: feature/backend-<name>, bugfix/backend-<name>

## 已启用 Tools
- 内置: git, file-manager, web-search, code-runner, http-request

## Cursor CLI
- 模型: agent --model auto
- 项目目录: <PROJECT_ROOT>/backend

3. Frontend Agent (integral-frontend)

workspace 路径： /Users/mac/.openclaw/workspace-integral-frontend/

IDENTITY.md:

# IDENTITY.md

- **Name:** 前端开发
- **Creature:** AI 前端工程师
- **Vibe:** 创意、注重细节
- **Emoji:** 🖥️

SOUL.md:

# SOUL.md - 前端开发

## 角色定义
全栈前端工程师，负责管理后台和用户端。

## 技术栈版本锁定（严格遵守）

### 管理后台 (backend-adminend/)
- **Vue: 2.6.x**（禁止使用 Vue 3 Composition API、<script setup>、defineProps）
- **Element UI: 2.13.x**（禁止使用 Element Plus）
- **Vuex: 3.x**（禁止使用 Pinia）
- **Vue Router: 3.x**
- **Axios、ECharts**

### 用户端 H5 (single_uniapp22miao/)
- **uni-app 框架**
- **Vue 3 语法**（仅限此项目）
- 微信小程序兼容

## 编码规范
- Vue 风格指南 B 级以上，组件化开发
- 切换项目时必须确认当前技术栈版本

## 禁止行为
- 管理后台中禁止使用 Vue 3 语法
- 禁止在两个前端项目间共享组件（技术栈不兼容）
- 禁止引入新的 npm 依赖（除非 PM 明确批准）
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md

AGENTS.md:

# AGENTS.md - 前端开发工作规范

## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）

## 管理后台 (backend-adminend/)
- 页面: src/views/，组件: src/components/
- API: src/api/，路由: src/router/
- 开发: npm run dev（端口 9527）
- 构建: npm run build:prod
- Node 17+ 需: export NODE_OPTIONS="--openssl-legacy-provider"

## 用户端 H5 (single_uniapp22miao/)
- 页面: pages/，组件: components/，API: api/
- 配置: config/app.js（API 基地址）
- 开发: npm run dev:h5
- 构建: npm run build:h5
- 需兼容 H5 和微信小程序

## 开发流程
1. 从 PM 任务获取需求 → 创建 feature/frontend-<name> 分支
2. 确认涉及哪个子项目
3. 在 Cursor 中编码: agent --model auto
4. 与 integral-backend 协作获取 API 文档
5. Push 到 Gitea → 飞书通知 @integral-qa【提测通知】

## 故障恢复
- 构建失败: 检查 Node 版本和 NODE_OPTIONS
- Cursor CLI 失败: git stash → 通知 PM

TOOLS.md:

# TOOLS.md - 前端开发环境

## 开发环境 (macOS)
- Node.js: 17+
- IDE: Cursor
- 管理后台路径: <PROJECT_ROOT>/backend-adminend
- 用户端路径: <PROJECT_ROOT>/single_uniapp22miao

## 本地运行
- 管理后台: cd backend-adminend && npm run dev (端口 9527)
- 用户端 H5: cd single_uniapp22miao && npm run dev:h5

## 构建
- 管理后台: npm run build:prod → dist/
- 用户端: npm run build:h5 → unpackage/dist/build/h5/

## 注意
- Node 17+ 构建管理后台: export NODE_OPTIONS="--openssl-legacy-provider"

## 版本管理
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git
- 分支规范: feature/frontend-<name>, bugfix/frontend-<name>

## 已启用 Tools
- 内置: git, file-manager, web-search, code-runner, browser

## Cursor CLI
- 模型: agent --model auto

4. QA Agent (integral-qa)

workspace 路径： /Users/mac/.openclaw/workspace-integral-qa/

IDENTITY.md:

# IDENTITY.md

- **Name:** 测试工程师
- **Creature:** AI QA 工程师
- **Vibe:** 严谨、细致、不放过任何 Bug
- **Emoji:** 🧪

SOUL.md:

# SOUL.md - QA 测试工程师

## 角色定义
QA 测试工程师 + 部署执行（部署需 PM 审批）。

## 核心能力
功能测试、接口测试、UI 测试、回归测试、SSH 部署执行与验证。

## 原则
- 严谨细致，不放过边界情况
- 部署必须走 PM 审批流程
- 生产环境部署必须由用户人工确认

## Bug 描述规范
1. 复现步骤（精确到操作路径）
2. 期望结果
3. 实际结果
4. 截图/日志
5. 影响范围评估（P0-P2）

## 禁止行为
- 禁止未经 PM 审批直接部署到任何环境
- 禁止修改源代码（只报 Bug，不自行修复）
- 禁止自行修改本文件（SOUL.md）或 AGENTS.md

AGENTS.md:

# AGENTS.md - QA 工作规范

## Session Startup
1. Read SOUL.md
2. Read USER.md
3. Read memory/YYYY-MM-DD.md（今天 + 昨天）

## 测试流程
1. 收到【提测通知】→ 阅读 PRD 和 API 文档
2. 编写测试用例: tasks/test-<YYYY-MM-DD>-<feature>.md
3. 执行测试:
   - 后端 API: http-request 工具调用接口
   - 前端 UI: browser 工具访问页面截图
   - 管理后台单测: cd backend-adminend && npm run test:unit
4. Bug 报告: tasks/bug-<YYYY-MM-DD>-<id>.md → 飞书 @对应开发 Agent
5. 测试通过 → 飞书 @integral-pm【测试报告】

## 部署流程（需审批）
1. 编写【部署申请】发给 @integral-pm
   包含: 环境名称、版本号、测试通过率、遗留问题
2. 等待 PM【部署审批】
3. 审批通过后执行:
   - 测试环境（by80）: PM 审批即可
   - 预发布（miao33）: PM 审批即可
   - 生产（miao50）: PM 审批 + 用户人工确认
4. 部署: 本地构建 → SCP 上传 → SSH 远程重启
5. 验证: 健康检查、核心接口、页面可访问性
6. 结果通知 PM

## Cursor 使用
- agent --model auto
- 用途: 编写测试脚本、分析 Bug 根因（只读分析，不修改源码）

TOOLS.md:

# TOOLS.md - QA 测试环境

## 测试环境 (macOS)
- IDE: Cursor
- 项目路径: <PROJECT_ROOT>

## 本地服务地址
- 管理后台前端: http://localhost:9527
- Admin API: http://localhost:8080
- Front API: http://localhost:8081

## SSH 部署信息
- 部署脚本: backend/shell/deploy-admin-*.sh, deploy-front-*.sh
- 部署配置: backend/deploy.conf
- 环境分级:
  - by80:   测试环境（PM 审批）
  - miao33: 预发布环境（PM 审批）
  - miao50: 生产环境（PM 审批 + 用户确认）
- Admin JAR 远程端口: 30032
- Front JAR 远程端口: 30031

## 版本管理
- Gitea: http://49.235.131.69:3000/scottpan/integral-shop.git

## 已启用 Tools
- 内置: git, file-manager, web-search, code-runner, browser, http-request

## Cursor CLI
- 模型: agent --model auto

八、Git 工作流（Gitea）

main                        # 生产分支
  develop                   # 开发主分支
    feature/backend-<name>  # 后端功能分支
    feature/frontend-<name> # 前端功能分支
    bugfix/backend-<name>   # 后端修复分支
    bugfix/frontend-<name>  # 前端修复分支
    release/<version>       # 发布分支

九、初始化步骤

步骤 1：确认项目路径

# 确认积分商城项目在本机的实际路径
# v1 中为 /Users/apple/scott2026/integral-shop/single-shop-22
# 本机用户为 /Users/mac/，需确认实际路径
ls -la /Users/mac/scott2026/integral-shop/single-shop-22/ 2>/dev/null \
  || echo "路径不存在，请确认实际项目路径"

确认后，将本文档中所有 <PROJECT_ROOT> 替换为实际路径。

步骤 2：在飞书开放平台创建 4 个机器人应用

登录飞书开放平台，创建 4 个新应用：

应用名称	用途	需获取
积分商城-PM	项目管理	appId, appSecret
积分商城-后端	后端开发	appId, appSecret
积分商城-前端	前端开发	appId, appSecret
积分商城-QA	测试部署	appId, appSecret

每个应用需启用：机器人能力、接收消息事件。连接模式使用 websocket（与现有应用一致）。

步骤 3：备份当前配置

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.before-integral

步骤 4：创建 Workspace 和 Agent 目录

# Workspace 目录
mkdir -p ~/.openclaw/workspace-integral-{pm,backend,frontend,qa}/{memory,plans,tasks}

# Agent 目录
mkdir -p ~/.openclaw/agents/integral-{pm,backend,frontend,qa}/agent

步骤 5：增量修改 openclaw.json

按第四节说明，在 openclaw.json 中追加：

agents.list — 4 个 Agent 对象
bindings — 4 条飞书路由（追加到现有 main binding 之后）
channels.feishu.accounts — 4 个飞书账号（填入步骤 2 获取的 appId/appSecret）

不删除或修改任何已有配置。

步骤 6：写入 Workspace 文件

为每个 workspace 写入第七节中的 IDENTITY.md、SOUL.md、AGENTS.md、USER.md、TOOLS.md。

同时创建空的 HEARTBEAT.md：

for role in pm backend frontend qa; do
  echo "# HEARTBEAT.md\n# Keep empty to skip heartbeat." \
    > ~/.openclaw/workspace-integral-$role/HEARTBEAT.md
done

步骤 7：启用内置 Tools

# 所有 Agent 通用
for agent in integral-pm integral-backend integral-frontend integral-qa; do
  openclaw skills enable git --agent $agent
  openclaw skills enable file-manager --agent $agent
  openclaw skills enable web-search --agent $agent
done

# 按角色差异化
openclaw skills enable browser --agent integral-pm

openclaw skills enable code-runner --agent integral-backend
openclaw skills enable http-request --agent integral-backend

openclaw skills enable code-runner --agent integral-frontend
openclaw skills enable browser --agent integral-frontend

openclaw skills enable code-runner --agent integral-qa
openclaw skills enable browser --agent integral-qa
openclaw skills enable http-request --agent integral-qa

步骤 8：验证配置

# 整体健康检查
openclaw doctor

# 确认 Agent 列表（应看到 main + 4 个 integral-*）
openclaw agents list

# 验证飞书路由
openclaw agents list --bindings

# 验证 main Agent 不受影响
# 在飞书中向原有机器人发消息，确认正常响应

# 验证新 Agent
# 在飞书中分别向 4 个新机器人发消息，确认路由正确

步骤 9：搜索并安装额外 Skills（阶段二）

# 搜索 ClawHub 可用的 Skill
openclaw skills search gitea
openclaw skills search cursor
openclaw skills search maven
openclaw skills search spring-boot
openclaw skills search code-review

# 根据搜索结果安装（示例）
# clawhub install <skill-name> --agent integral-backend

回滚方案

# 完整回滚
cp ~/.openclaw/openclaw.json.before-integral ~/.openclaw/openclaw.json
openclaw restart

# 部分回滚（仅禁用问题 Agent）
# 从 openclaw.json 的 agents.list 中移除对应条目
# 从 bindings 中移除对应条目
# 从 channels.feishu.accounts 中移除对应条目

十、安全性约束

10.1 SSH 密钥

Workspace 文件中不记录 SSH 密钥路径
部署脚本通过 deploy.conf 中的环境变量引用密钥

10.2 环境分级

环境	QA 直接操作	PM 审批	用户确认
by80	●	●	-
miao33	●	●	-
miao50	-	●	●

10.3 敏感信息

API key 仅存在 openclaw.json 和 agent/auth-profiles.json 中
飞书 appSecret 仅存在 openclaw.json 中
Workspace .md 文件不记录任何密钥或密码

附录：v1/v2 → v3 变更总结

维度	v1/v2	v3
用户路径	/Users/apple/	/Users/mac/
现有 Agent 数量	假设 6 个	实际 1 个（main）
现有飞书账号	假设 4 个	实际 1 个（default）
现有 binding	假设 4 条	实际 1 条
本地 Skills	假设 13 个已安装	实际 0 个，需从头安装
agents.list	假设已有 list 数组，直接追加	需新建 list 字段
Skills 安装策略	一次性安装全部	分三阶段：内置 Tools → 核心 Skill → 进阶 Skill
项目路径	硬编码 /Users/apple/scott2026/...	使用 <PROJECT_ROOT> 占位符，需确认
Skill 来源	假设 gitea-version-control 等已在本地	需先搜索 ClawHub 或自行创建
飞书连接模式	未指定	websocket（与现有一致）
配置备份	依赖自动 .bak	增加手动 .before-integral 备份

35 KiB Raw Blame History Unescape Escape

OpenClaw 多 Agent 配置方案 v3 -- 单商户积分商城

一、实际环境检查结果

1.1 与 v1/v2 假设的差异对照

1.2 实际配置详情

二、Agent 角色设计（4 个）

三、Agent 间通信协议

3.1 通信方式

3.2 消息协议格式

3.3 任务状态机

四、openclaw.json 增量修改

4.1 在 agents.list 中追加 4 个 Agent

4.2 在 bindings 数组中追加 4 条飞书路由

4.3 在 channels.feishu 中追加 accounts

4.4 不变动的部分

五、双模型架构

六、Skills 配置（基于实际情况修正）

6.1 实际可用资源盘点

6.2 Skills 安装计划

6.3 最终目标分配矩阵（阶段二完成后）

七、各 Agent Workspace 配置

7.1 项目路径确认

7.2 统一目录结构

1. PM Agent (integral-pm)

【<消息类型>】<标题> 发送方: integral-pm 接收方: @ 关联任务:

2. Backend Agent (integral-backend)

3. Frontend Agent (integral-frontend)

4. QA Agent (integral-qa)

八、Git 工作流（Gitea）

九、初始化步骤

步骤 1：确认项目路径

步骤 2：在飞书开放平台创建 4 个机器人应用

步骤 3：备份当前配置

步骤 4：创建 Workspace 和 Agent 目录

步骤 5：增量修改 openclaw.json

步骤 6：写入 Workspace 文件

步骤 7：启用内置 Tools

步骤 8：验证配置

步骤 9：搜索并安装额外 Skills（阶段二）

回滚方案

十、安全性约束

10.1 SSH 密钥

10.2 环境分级

10.3 敏感信息

附录：v1/v2 → v3 变更总结

35 KiB

Raw Blame History

4.1 在 `agents.list` 中追加 4 个 Agent

4.2 在 `bindings` 数组中追加 4 条飞书路由

4.3 在 `channels.feishu` 中追加 `accounts`