OpenClaw与iCode多Agent系统协作改造实践

引言：运维工程师如何改造多智能体协作工具

在飞鱼 Admin 项目中，我们运维团队近期面临一项关键任务：对由13个独立AI Agent构成的多智能体协作系统进行深度改造。

该系统在理念上颇具吸引力——技术、市场、产品、测试等角色在飞书群中各司其职，协同工作。然而，实际运行中问题频发：消息丢失、记忆系统混乱、Bot间协作不畅、代码质量隐患巨大，每次上线都如同扫雷。技术债务持续累积。

从运维视角看，系统稳定性至关重要。但对于此类协作系统，“稳定”的内涵已扩展为：信息可靠传递、决策过程可追溯、任务执行必有回响。

本次改造计划为期两天。本文聚焦首日核心工作：研究部署iCode、搭建PHPStan质量保障体系、初步构建多Agent技能体系。这些基础工作是系统能否成功蜕变的关键。

一、系统改造的背景与目标

1.1 改造前的系统核心问题

改造前，系统主要存在四大痛点：

问题一：记忆丢失

每日零点，所有Bot的会话均被重置。导致前日的开发计划、技术决策、人员分工等讨论内容全部消失，团队每日需重复沟通，效率低下。

问题二：跨 Bot 通信失效

在飞书群中@特定Bot，响应具有不确定性。常因Bot的飞书open_id变更未同步配置，导致消息静默丢失，问题发现滞后。

问题三：代码质量无保障

飞鱼Admin作为基于ThinkPHP 8的PHP项目，缺乏静态检查与质量门槛，代码历史包袱重，上线风险高。

问题四：技能不成体系

Bot处理任务缺乏标准化流程，相同任务可能由不同Bot以迥异方式完成，结果难以预期与管理。

1.2 明确的改造目标

针对上述问题，我们设定了四个清晰目标：

目标一：记忆不丢失 —— 实现跨日会话可追溯
目标二：通信必达 —— 确保跨 Bot 消息可靠路由
目标三：质量前置 —— 代码改动必须通过检查
目标四：技能标准化 —— 为每个 Bot 赋予专业能力

二、iCode：思维方式的革新

2.1 iCode 的核心价值

iCode本质上是Claude Code的进阶工具包。其价值不仅在于功能，更在于其设计哲学。其源码结构清晰，所有能力都以独立skill形式组织于src/skills/bundled/目录。这种透明化设计便于深度定制与思想借鉴。

2.2 iCode 部署实践

部署环境信息如下：

部署路径：/www/wwwroot/icode/iCode-main/
API：MiniMax-M2.7-highspeed
端点：https://api.minimaxi.com/anthropic

部署关键在于对三个核心文件应用补丁：

// preflightChecks.tsx — 调整预检逻辑
// oauth.ts — 修改认证流程
// client.ts — 增加自定义 baseURL 支持（对接 MiniMax API 的关键）

配置完成后，通过SSH在服务器运行./icode命令即可交互使用。

2.3 从 iCode 汲取的技能体系

iCode的skills目录提供了14个精心设计的提示词模板，其中三个极具启发性：

技能一：batch — 并行任务编排

该技能打破传统串行处理模式，可同时启动5至30个独立分析Agent并行工作，最后汇总结果。其简化逻辑模型如下：

const forks = tasks.map(task => ({
  name: task.name,
  description: task.description,
  prompt: `针对 ${task.target}，执行以下任务：${task.instruction}`
}))
// 所有 fork 共享 prompt cache，零额外开销

适用于大规模代码重构、多模块并行调研、多接口并行测试等场景，能带来数十倍的效率提升。

技能二：simplify — 三视角并行审查

该技能同时启动三个Agent，从不同专业视角审查同一份代码：

Agent1（复用视角）：检查重复代码与抽象可能性。
Agent2（质量视角）：检查 hack、冗余、安全漏洞与边界条件。
Agent3（效率视角）：检查 N+1 查询、重复计算、内存泄漏与阻塞操作。

最终汇总生成全面改进报告，审查全面性远超单人审查。

技能三：verify — 运行验证原则

该技能强调“不运行，不算验证”，内置四种验证模式：

模式一：CLI 验证
适用于命令、脚本、工具升级等场景。

# 验证 PHP 文件语法
php -l /path/to/file.php
# 验证 Docker 配置
docker ps
# 验证 nginx 配置
nginx -t
# 检查退出码
command && echo "SUCCESS" || echo "FAILED"

模式二：HTTP 验证
适用于API、登录流程、接口修复等场景。

# 获取 token
TOKEN=$(curl -s -X POST http://localhost:8088/adminapi/login/account -d '{"username":"admin","password":"admin123"}' | jq -r '.data.token')
# 验证用户列表接口
curl -s http://localhost:8088/adminapi/user/lists -H "Authorization: Bearer $TOKEN" | jq .
# NL2SQL 接口验证
curl -s -X POST http://localhost:8088/adminapi/nl2sql/query -H "Authorization: Bearer $TOKEN" -d '{"question":"用户总数"}' | jq .

模式三：服务验证
适用于部署重启、容器启动、进程存活检查等场景。

# 进程存活
ps aux | grep feiyuadmin | grep -v grep
# 端口监听
ss -tlnp | grep 8088
# 日志无报错
tail -20 /www/wwwlogs/feiyuadmin-error.log | grep -i error
# 健康端点
curl -f http://localhost:8088/health 2>/dev/null && echo "OK" || echo "FAIL"

模式四：数据库验证
适用于数据迁移、初始化、数据完整性检查等场景。

# 迁移状态
docker exec feiyuadmin-php php artisan migrate:status
# 数据查询
docker exec feiyuadmin-mysql mysql -u root -p -e "SELECT COUNT(*) FROM fy_users"
# 连接测试
docker exec feiyuadmin-mysql mysql -u root -p -e "SELECT 1"

三、PHPStan：构建代码质量基础设施

3.1 静态检查的必要性

代码质量问题的修复成本随发现时间推迟呈指数增长。静态检查的核心价值在于将问题发现时机提前至开发阶段，从而大幅降低风险与成本。

3.2 选择 Level 5 的考量

PHPStan提供0至9十个检查级别。我们选择Level 5是基于以下权衡：

级别	检查内容	误报率
Level 0-4	基础类型安全	低
Level 5	空指针、类型不安全、魔法数字	中
Level 6-9	极度严格	高

Level 5在覆盖高置信度问题（如空指针调用）与可控误报率之间取得了平衡，更易于团队接受和执行。

3.3 基线机制：渐进式质量提升

当前PHPStan配置状态如下：

检查级别：Level 5
已知错误数：1135 个
处理方式：记录在 phpstan-baseline.neon（基线文件）
新错误：实时拦截
旧错误：逐步清理
钩子：pre-commit hook 已配置

基线机制采用渐进式策略：将1135个历史错误记录于基线文件，不阻塞当前提交；仅拦截新引入的错误。这使得团队能在不影响开发节奏的前提下，有序清理技术债务。

四、构建专业化的多 Agent 技能体系

4.1 技能体系的价值

对于13个独立AI Agent的系统，每个Agent需明确：何时行动（knowing what to do）与如何行动（knowing how to do it）。技能体系将标准化流程封装为可复用工具，使Agent只需调用相应技能，无需每次重新学习复杂步骤。

4.2 部署的技能矩阵

技能	功能	解决的问题
code-tools	Grep/Glob/Edit/Task/Bash	高频工具统一接口
code-explore	只读代码探索	防止误改关键文件
code-plan	软件架构规划	大任务分解路径
code-verify	对抗性验证	寻找薄弱环节
code-review	安全+并发+边界审查	上线前最后关卡
code-simplify	三视角并行审查	复用/质量/效率全覆盖
code-semantic	语义级符号理解	跳转到定义、查找引用
team-coord	多 Bot 协作调度	复杂任务并行协调
memory-organizer	三层记忆整理	短期→长期的正确流动

4.3 team-coord 的设计哲学

team-coord技能借鉴iCode的Coordinator Mode，其工作流清晰：

Phase 1：并行研究 — 任务同时发给相关 Bot 分头调查。
Phase 2：综合理解 — 协调者消化所有调查结果并产出具体方案。
Phase 3：执行分配 — 给出具体的文件路径、行号、成功标准。
Phase 4：验证 — 必须提供实测结果，而非口头承诺。

核心原则是“Never delegate understanding”（绝不委托理解）：协调者需将任务分解至极度具体（如文件路径、行号、具体操作），使执行者无需猜测意图，只需专注执行，从而提升协作效率与准确性。

五、归档机制：根治跨日会话丢失

5.1 问题根源

多数AI系统因上下文窗口有限，会在每日零点重置会话，导致历史讨论丢失。这对需要连续性的工作场景是严重缺陷。

5.2 全系统每日归档方案

我们部署了统一的自动化归档机制：

# /etc/cron.d/openclaw-archive
0 2 * * * /root/.openclaw/scripts/archive-all-bots.sh
# 覆盖范围（8个 Bot）：
# mayun, liujq, liyanh, zhouhy,
# wangj, mahuit, mengyt, daji

每日凌晨2点，该任务将各Bot当日会话整理为memory/YYYY-MM-DD.md文件，实现历史可查、快速恢复与跨Bot信息共享。

5.3 归档脚本核心逻辑

归档脚本逻辑简洁有效：

# 伪代码
for bot in $COVERED_BOTS; do
  session_file="/root/.openclaw/agents/$bot/sessions/sessions.json"
  # 读取当日会话
  today_session=$(filter_by_date $session_file $(date +%Y-%m-%d))
  # 整理成标准格式
  formatted=$(format_as_markdown $today_session)
  # 写入归档
  echo "$formatted" >> /root/.openclaw/workspace-$bot/memory/$(date +%Y-%m-%d).md
done

六、首日改造的核心收获

6.1 理解工具重于使用工具

iCode的最大启示在于其方法论：将能力封装为标准技能并清晰文档化设计思想。当每个Agent理解“为何如此设计”时，才能实现高效协作，而非机械执行模糊指令。

6.2 质量基础设施需先行

PHPStan配合pre-commit hook，使代码质量检查从“额外任务”变为“提交自动环节”。在开发阶段发现并修复问题的成本，远低于上线后处理。质量关卡前置是提升长期研发效率的关键。

6.3 协作核心是“理解”而非“分配”

team-coord技能强调的“协调者先理解，后分配”原则具有普适性。许多团队协作低效的根源在于分配者未厘清需求便抛出模糊任务。清晰的指令与上下文是高效协作的基石。

结语

首日改造聚焦于基础设施搭建与协作规范确立。

这些工作虽不炫目，却是后续深度改造的基石。当代码质量得以保障、Agent职责清晰、跨日记忆可追溯，第二天的攻坚战——飞书relay路由修复、记忆系统iCode Taxonomy改造、精准多Bot协作框架构建——才成为可能。

真正的系统优化，往往始于这些至关重要且扎实的基础建设。