如果你一直在用 OpenClaw，你可能注意到了——从 2026 年 5 月开始，openclaw 核心包突然”瘦”了。启动速度快了，内存占用降了，但功能一个没少。

这不是魔法，这是 Plugin Externalization——OpenClaw 5.x 最重要的架构变革。

把时钟拨回 4.24 版本：所有官方插件（Discord、Telegram、WhatsApp、Matrix、Feishu、诊断工具……）都打包在一个巨大的 openclaw npm 包里。不管你用不用 Discord，它的代码都在那里，占着内存、拖着启动。

5.x 的答案：每个插件独立发包，按需安装，ClawPack 元数据保障完整性。

架构对比：Before vs After

4.24 时代（Monolithic）

openclaw@2026.4.24
├── core/
├── plugins/          ← 所有插件编译进核心
│   ├── discord/
│   ├── telegram/
│   ├── whatsapp/
│   ├── feishu/
│   ├── matrix/
│   ├── diagnostics-otel/
│   ├── acpx/
│   └── ... (30+ plugins)
└── dist/

问题：

• 安装体积大（未使用的插件也占空间）
• 启动时扫描/加载所有插件
• 一个插件的依赖更新要发布整个核心包
• 第三方插件与官方插件走不同生命周期

5.x 时代（npm-first + ClawPack）

openclaw@2026.5.6          ← 精简核心
├── core/
├── plugins/               ← 仅保留轻量内置插件
└── dist/

~/.openclaw/plugins/       ← 按需安装
├── @openclaw/discord/
├── @openclaw/feishu/
├── @openclaw/acpx/
└── @openclaw/diagnostics-otel/

收益：

• 核心包体积减少 ~40%
• 启动只加载实际配置的插件
• 插件可独立更新，不绑定核心版本
• 统一的生命周期：官方 = 第三方

五大核心变化详解

1. ClawPack 分发体系

ClawPack 是 5.x 引入的插件分发元数据标准：

• 版本化 Artifact：每个插件发布带 digest 校验
• 完整性验证：下载时验证 response headers + bytes
• 安装记录持久化：ClawHub 安装记录携带 artifact 元数据
• 双通道分发：ClawHub（主）+ npm（备选）

# 安装官方外部插件
openclaw plugins install @openclaw/discord

# 查看插件依赖状态
openclaw plugins list --json

2. Tool Descriptor 缓存（5.2）

这是对性能影响最大的改动之一。

Before：每次 prompt 构建都要加载插件运行时，遍历注册的 tools，序列化描述符。

After：

1. 插件通过 api.registerTool() 注册 tool 时，描述符被缓存
2. prompt 构建时直接读缓存，跳过插件运行时加载
3. 只有实际执行 tool 时才加载完整插件

Prompt 构建: Plugin Registry → Cached Descriptors → Model (无需加载插件)
Tool 执行:   Model Response → Load Plugin → Execute Handler

实测效果：prompt 准备阶段的插件加载开销接近归零。

3. 精准加载策略（5.2）

4.24 的启动逻辑：

// 旧：扫描所有可发现的插件并导入
for (const plugin of discoverAllPlugins()) {
  await import(plugin)
}

5.x 的启动逻辑：

// 新：只加载必要的插件
const needed = resolveFromConfig(config)    // config 中声明的
  .concat(resolveFromChannels(channels))     // channel 需要的
  .concat(resolveAutoEnable(rules))          // 自动启用规则命中的
  
for (const plugin of needed) {
  await import(plugin)
}

4. file-transfer 插件（5.3 新增）

5.3 带来了一个实用的内置插件：

安全策略：

• 默认拒绝所有路径，需在 plugins.entries.file-transfer.config.nodes 中显式配置
• 单次传输上限 16MB
• symlink 默认不跟踪（需 opt-in followSymlinks）
• 需 operator approval

5. 安装安全扫描器优化（5.3 → 5.6）

5.3 引入了安装扫描器（install scanner），检测插件包中的可疑行为：

• process.env 访问
• 网络请求模式
• 文件系统操作

但 5.3 的扫描器太激进——官方打包插件的 compiled bundle 中，process.env 和正常 API 调用在同一个编译产物的不同位置出现，也会被拦截。

5.6 修复：当 process.env 访问和 API sends 出现在同一个编译 bundle 的不同区域时，不再阻断官方插件安装。

性能实测

基于 5.2 release notes 中提到的优化，Gateway 启动热路径的改进包括：

官方称这些优化让 Gateway 启动 “reaches readiness faster”，具体数字取决于配置的插件数量。

插件开发者需要知道的

如果你在开发 OpenClaw 插件，5.x 带来几个重要变化：

发布路径

# 推荐：通过 ClawHub 发布
openclaw plugins publish

# 备选：直接 npm 发布
npm publish --access public

Beta 通道

如果你的 OpenClaw 在 beta 更新通道上：

• 插件更新会优先尝试 @beta 标签
• 没有 beta release 时自动降级到 latest

诊断与修复

# 查看插件状态（含依赖信息）
openclaw plugins list --json

# 修复插件问题
openclaw doctor --fix

# doctor 现在能处理：
# - 缺失的插件包
# - 过期的安装记录
# - 外部化迁移
# - source-only 包警告

SecretRef 契约

外部化的 channel 插件需要在 dist/ 目录下暴露 secret-contract-api，否则 Gateway 启动时 SecretRef 解析会失败（5.4 修复了这个路径问题）。

对 ClawGuard 的影响

作为插件评估框架的开发者，这些变化对 ClawGuard 意味着：

1. 评估目标变了：从评估 bundled 代码到评估独立 npm 包
2. 安装扫描器是竞品也是参考：OpenClaw 内置的扫描器覆盖了基础安全检测
3. ClawPack 元数据可利用：digest 验证可作为 SEC 维度的输入
4. 新的 probe 机会：openclaw plugins list --json 暴露的依赖状态可供分析

总结

OpenClaw 5.x 的 Plugin Externalization 不是简单的”拆包”，而是一次完整的生态架构升级：

这是 OpenClaw 走向真正插件生态的关键一步。当插件的安装、更新、审计、修复都有标准化流程时，社区贡献的门槛就降下来了。

基于 OpenClaw v2026.4.24 → v2026.5.6 的 Release Notes 整理分析。

用过 AI Agent 的人都有这种体验：

你纠正了 Agent 一次：”下次记得先验证图片是不是动图，别直接用。”

它在 Memory 里记了一笔。

但下次真遇到类似场景，它可能记住了”要验证”，却忘了具体该验证什么、怎么验证、验证后该做什么。

问题的本质：Memory 擅长存事实，但不擅长存流程。

“用户喜欢蓝色”是事实，存 Memory 没问题。但”拿到外部 GIF 后先验证是否真动图、再记录版权、再本地存副本、最后在产品 UI 确认渲染”——这是程序性知识，它需要的是一份 SOP，不是一条记忆。

Skill Workshop：程序性记忆系统

OpenClaw 最近推出的 Skill Workshop 插件，正是解决这个问题的答案。

一句话定义：

Skill Workshop 让 Agent 从工作经验中自动提炼可复用的 SKILL.md 文件。

它的输出是标准的 SKILL.md 文件，存放在 <workspace>/skills/ 目录下，和手写的 Skill 享受完全相同的加载、优先级、门控机制。

工作原理：三条捕获路径

路径一：显式调用

Agent 识别到可复用流程时，直接调用 skill_workshop tool：

{
  "action": "suggest",
  "skillName": "animated-gif-workflow",
  "title": "Animated GIF Workflow",
  "description": "验证动图资产的完整流程",
  "body": "## Workflow\n\n- 验证 URL 返回 image/gif\n- 确认包含多帧\n- 记录版权归属\n- 本地存储副本"
}

这是最可控的方式，即使关闭自动捕获也能使用。

路径二：启发式捕获

当用户说出”纠正性语句”时，自动触发：

捕获后自动分类到对应 skill：

• GIF 相关 → animated-gif-workflow
• 截图相关 → screenshot-asset-workflow
• QA 相关 → qa-scenario-workflow
• GitHub PR → github-pr-workflow
• 其他 → learned-workflows

路径三：LLM Reviewer

这是最智能的路径。达到阈值后（默认 15 次 agent turn 或 8 次 tool call），系统启动一个嵌入式 LLM 审查器：

输入：

• 最近 12,000 字符的对话 transcript
• 当前 workspace 最多 12 个已有 skill（每个最多 2,000 字符）

输出：

• { "action": "none" } — 没发现值得提炼的
• { "action": "create", ... } — 创建新 skill
• { "action": "append", ... } — 追加到已有 skill
• { "action": "replace", ... } — 替换已有 skill 中的内容

关键约束：reviewer 没有任何工具权限（disableTools: true），只做纯文本分析，不会产生副作用。

安全设计：Proposal 审批制

Skill Workshop 不会直接改你的文件。每个捕获结果都经过一条安全管线：

捕获/提炼
    ↓
内容扫描器（检测危险模式）
    ↓
┌─────────────────────┐
│ 安全？               │
├─ ✅ safe ────→ pending（等待审批）或 auto-apply
└─ ❌ critical ─→ quarantine（隔离，无法 apply）

Proposal 状态机

pending ──→ applied（批准写入）
   │
   └──→ rejected（拒绝）

quarantined（永不自动写入，需人工干预）

写入限制

• 目录限制：只写入 <workspace>/skills/<skill-name>/
• 文件大小限制：默认 40KB
• 支持文件：只允许 references/、templates/、scripts/、assets/ 子目录
• 名称规范化：强制小写 + [a-z0-9_-]
• 去重：相同 skill name + 相同 change payload 自动去重

配置指南

最小安全配置（推荐起步）

{
  plugins: {
    entries: {
      "skill-workshop": {
        enabled: true,
        config: {
          autoCapture: true,
          approvalPolicy: "pending",  // 人工审批
          reviewMode: "hybrid"        // 启发式 + LLM
        }
      }
    }
  }
}

四种预设 Profile

关键参数

实战场景

场景一：博客发布流程沉淀

用户多次纠正 Agent 的博客发布流程后，Skill Workshop 自动提炼：

---
name: blog-publish-workflow
description: 博客文章发布的标准操作流程
---

## Workflow

1. 查看最近 3 张配图，确保风格不重复
2. 生成配图（禁止深蓝紫霓虹风格）
3. 文章不带内部链接
4. Front matter 必须包含 overlay_image
5. git commit & push
6. 第一时间告知用户结果

场景二：代码审查规程

---
name: code-review-workflow
description: PR 代码审查标准流程
---

## Before Review

- Check unresolved threads
- Verify CI status
- Read linked issues

## During Review

- Focus on logic errors over style
- Check error handling paths
- Verify test coverage for changed code

场景三：调研报告规范

---
name: research-report-workflow
description: 技术调研报告的质量标准
---

## 数据源要求

- 每个产品至少 3 种搜索策略交叉验证
- GitHub Stars/Forks/Release 频率必查
- 数据标注来源和日期
- 搜不到如实标注"未公开"

## 输出要求

- 覆盖完整赛道，主动发现未知玩家
- 有判断力，不只搬运信息
- 矛盾数据标注争议

与现有方案的对比

Skill Workshop 的独特价值在于：它产出的是结构化的、可直接加载的 SKILL.md，而不是散落在 memory 文件里的经验碎片。

设计哲学

Skill Workshop 的设计体现了几个值得玩味的理念：

1. 程序性记忆 ≠ 陈述性记忆

认知科学早就区分了”知道是什么”和”知道怎么做”。Skill Workshop 是 AI Agent 领域第一个认真对待这个区分的实现。

2. 安全优先于便利

默认关闭、默认审批、内容扫描、隔离机制——宁可漏掉一条有用 skill，也不写入一条有害内容。

3. 渐进式信任

从 pending（人工审批）起步，观察质量稳定后才切 auto。不是”要么全自动要么没用”的二选一。

4. 与 Skill 生态无缝衔接

产出的文件和手写 Skill 完全等价，享受同样的优先级、门控、agent allowlist、ClawHub 分发。

风险提示

⚠️ 实验性特性：capture 启发式和 reviewer prompt 可能随版本变化

⚠️ LLM 成本：hybrid 模式下每 15 turns 触发一次 reviewer 调用

⚠️ 不适合多人/不可信环境：恶意输入可能触发误导性 proposal

⚠️ 不替代 Memory：事实类信息（”用户名是 xxx”）不该走 Skill Workshop

总结

Skill Workshop 解决了一个长期痛点：Agent 的流程性知识如何持久化和复用？

它的答案是：

• 从对话中自动捕获可复用流程
• 通过安全审查过滤危险内容
• 经人工审批后写入标准 Skill 文件
• 下次遇到类似任务，直接按 SOP 执行

这让 Agent 从”每次都像新人”进化为”有经验的老员工”——而且这份经验是可审计、可编辑、可分享的。

基于 OpenClaw 官方文档 Skill Workshop Plugin 整理分析。当前为实验性特性，API 可能变化。

Symphony 是一个将项目管理看板（Linear）变成 AI 编程 Agent 编排控制面板的开源规范——每一个未关闭的 Issue 自动对应一个独立 Agent，7×24 不间断执行，人类只需要 review 结果。

部分团队在上线 3 周内，landed PR 数量增长了 500%。

背景：为什么需要 Symphony？

前传：Harness Engineering

六个月前，OpenAI 内部一个团队做了一个激进实验：仓库中 0 行人写代码，所有代码必须由 Codex 生成。为此他们重新设计了工程工作流，打造了”Agent-friendly repository”——完善的自动化测试、guardrails、文档，把 Codex 当成正式队友。

这个方法奏效了。但随即撞上了下一个瓶颈：上下文切换。

人类注意力成为系统瓶颈

当 Agent 工作规模扩大后，工程师的日常变成了：

打开 3-5 个 Codex 会话 → 分配任务 → 审查产出 → 纠偏 → 重复

超过 5 个并行会话后，生产力骤降。工程师忘了哪个 session 在做什么，在终端间跳来跳去，调试卡住的长任务。

本质问题：Agent 已经很快了，但人类成了瓶颈。他们相当于雇了一堆极其能干的初级工程师，然后让高级工程师去”微管理”他们——这不 scale。

视角转换

关键洞察：他们一直在优化错误的东西。

之前围绕”Codex 会话”和”PR”组织工作，但会话和 PR 只是手段，不是目的。软件工程的工作实际上围绕交付物组织：Issue、任务、里程碑。

于是他们问了一个问题：如果不再直接监督 Agent，而是让 Agent 自己从任务看板拉取工作会怎样？

这就是 Symphony 的起点。

核心架构：Issue Tracker = Agent 控制面板

基本运作模式

┌─────────────────────────────────────────────────────┐
│                    Linear 看板                        │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐          │
│  │Todo │ │In   │ │Human│ │Merg-│ │Done │          │
│  │     │ │Prog │ │Revw │ │ ing │ │     │          │
│  └──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘ └─────┘          │
└─────┼────────┼───────┼───────┼──────────────────────┘
      │        │       │       │
      ▼        ▼       ▼       ▼
┌─────────────────────────────────────────────────────┐
│              Symphony Orchestrator                    │
│                                                      │
│  • 持续轮询看板                                       │
│  • 每个活跃 Issue → 独立 Workspace → 独立 Agent      │
│  • Agent 崩溃 → 自动重启                             │
│  • 新任务 → 立即认领                                  │
│  • DAG 依赖 → 自动按序执行                           │
│  • 指数退避重试                                       │
└─────────────────────────────────────────────────────┘

六层架构

Symphony 规范定义了清晰的六层分离：

核心组件

1. Workflow Loader — 读取 WORKFLOW.md，解析 YAML front matter + prompt body
2. Issue Tracker Client — 拉取活跃 Issue，归一化为统一模型
3. Orchestrator — 调度核心：轮询、分派、重试、停止、释放
4. Workspace Manager — Issue → 独立目录映射，生命周期钩子
5. Agent Runner — 构建 prompt，启动 Codex app-server，流式回传状态
6. Status Surface — 可选的人类可读状态展示

关键设计决策

DAG 任务编排：自动发现最优并行路径

Symphony 最强大的能力之一是任务依赖图（DAG）编排：

示例：React 升级项目

                ┌── Vite 迁移 ──┐
                │               │
分析代码库 ──────┤               ├── React 升级 ── 集成测试 ── 完成
                │               │
                └── 清理旧依赖 ──┘

• Agent 可以自动将大任务拆解为子任务树
• 有阻塞关系的任务按序执行
• 无依赖的任务自动并行
• Agent 还会自主创建新 Issue（发现重构机会、性能问题等）

这意味着 Symphony 不只是一个执行器，而是一个能自我扩展工作范围的系统。

关键数据与效果

深层洞察：四条工程哲学

1. “给目标，不给步骤”

We moved toward giving agents objectives instead of strict transitions, much like a good manager would assign a goal to a direct report.

早期他们把 Agent 当状态机的刚性节点——只做”实现这个功能”。后来发现 Codex 完全可以：创建多个 PR、读取 review 反馈并修复、关闭过期 PR、生成完成报告。

教训：模型越来越聪明，不要限制在你为它设计的盒子里。给工具、给上下文、让它自己想办法。

2. “失败成本趋近于零”

If the agent gets something wrong, that’s still useful information, and the cost to us is near zero.

这彻底改变了团队行为：随手创建探索性任务、试想法、试重构、试假设，只保留有价值的结果。

当每次尝试的边际成本趋近于零时，探索的总量会爆发式增长。

3. “不要修结果，修系统”

Instead of patching the result manually, we added guardrails and skills so the agents could succeed the next time.

Agent 产出质量不够时，不手动改输出，而是增加 E2E 测试、增加 Chrome DevTools 集成、改善文档、明确”什么算好”。

投资系统性解法，而不是一次性补丁。这是一个正反馈飞轮。

4. “Symphony 用 Symphony 来构建 Symphony”

仓库里的核心只是一个 SPEC.md——问题定义和解法规范。他们把 SPEC 交给 Codex，让 Codex 来实现 Symphony 本身。

这展示了一种新的软件开发范式：规范驱动开发（Spec-Driven Development）。人类写 Spec，Agent 写实现。

局限性与适用边界

不适合的场景恰恰是人类工程师最有趣、最值得花时间的工作——这正是设计意图：让 Agent 处理大量常规实现，让人聚焦于真正有挑战性的单一难题。

与现有方案的对比

对行业的启示

“Agent 管理”将消亡，”工作管理”将崛起

旧世界：人管理 Agent 会话 → 人是瓶颈
新世界：人管理工作看板 → Agent 是执行层 → 无限并行

这意味着：

• 项目管理工具（Linear、Jira、GitHub Issues）将进化为 Agent 编排平面
• PM 的角色从”写需求给工程师”变为”写需求给 Agent”
• 工程师的角色从”写代码”变为”设计系统让 Agent 能正确写代码”

“Harness Engineering” 是前置条件

Symphony 能工作的前提是仓库已经是 Agent-friendly 的：完善的自动化测试、清晰的文档、好的 guardrails、明确的质量定义。

没有 Harness Engineering 的基础，直接上 Symphony 会是灾难。

规范优于实现

Symphony 选择开源一个 SPEC 而不是一个产品——任何语言都能实现、任何 Issue Tracker 都能适配、任何 Agent 都能对接。这比开源一个耦合的产品有更大的生态潜力。

实践建议：如何在自己团队落地

Step 1: 评估准备度

• 仓库有 CI/CD 和自动化测试？覆盖率 > 70%？
• 有清晰的文档和编码规范？
• 有明确的 PR review 标准？

Step 2: 小范围试点

• 选择相对独立的子系统
• 创建 WORKFLOW.md 定义 Agent 行为策略
• 从简单、可验证的任务开始

Step 3: 逐步扩大

• 观察失败模式 → 补 guardrails
• 培训非工程角色直接提交任务
• 建立度量体系（成功率、干预率、PR 质量）

Step 4: 文化转变

• 接受”试错零成本”的心态
• 把 Agent 失败当成系统改进的信号
• 人类聚焦高判断力工作

结语

Symphony 不是又一个 AI 编程工具——它是一种工程组织方式的范式转变。

它回答的核心问题是：当 Agent 能力已经足够时，瓶颈在哪里？

答案是：在人类的注意力和组织方式上。

Symphony 的解法优雅而实用：不去做更好的 Agent，而是改变人和 Agent 的协作方式——从”微管理”变为”目标驱动”，从”会话级”变为”工作级”，从”一对一”变为”一对多自动编排”。

对于任何规模化使用 AI Agent 的团队来说，这个规范都值得深入研究。不管你用不用 Codex，Symphony 提出的思想和架构模式是跨平台、跨工具的普适原则。

Claude Code 不是代码补全工具，不是聊天窗口里的问答机器人——它是一个真正的 AI 编程代理。你描述目标，它自主规划、编码、测试、提交。整个过程你可以去倒杯咖啡。

在 2026 年 Pragmatic Engineer 对 15,000 名开发者的调查中，Claude Code 以 46% 的”最受喜爱”票数碾压 Cursor（19%）和 Copilot（9%），成为开发者心中的第一选择。

这篇文章不讲概念，只讲实操——帮你从零搭建一个高效的 Claude Code 编程环境。

Claude Code 是什么，为什么它不一样

先搞清一个核心概念：Agentic Coding（代理式编程）。

Claude Code 的工作方式是一个 Agentic Loop（代理循环）：

描述任务 → 规划步骤 → 读文件/写文件/跑命令/搜代码 → 验证结果 → 成功则完成，失败则回到执行

它拥有 200K Token 上下文窗口，内置读写文件、执行命令、代码搜索、子代理调用等工具，还支持通过 MCP 协议扩展外部服务。

支持的平台：终端 CLI（原生体验最佳）、VS Code 扩展、JetBrains Beta、Desktop App（macOS + Windows）。

安装一行搞定：

curl -fsSL https://claude.ai/install.sh | bash

中国大陆怎么接入

这是国内开发者最关心的问题。三种方案，按推荐度排序。

方案一：代理直连（推荐）⭐⭐⭐⭐⭐

如果你已有 Clash 等代理工具，只需配置环境变量：

# 在 .zshrc 或 .bashrc 中添加
export https_proxy=http://127.0.0.1:7897
export http_proxy=http://127.0.0.1:7897
export all_proxy=socks5://127.0.0.1:7897
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

防封号关键：建议配置静态住宅 IP 链式代理。原理是在你的机场节点后面再套一层住宅 IP，让 Anthropic 看到的始终是固定的住宅出口：

# Clash 链式代理配置
proxies_group:
  name: claude-chain
  type: relay
  proxies:
    - 机场节点
    - 静态住宅IP
rules:
  - DOMAIN-KEYWORD,claude,claude-chain
  - DOMAIN-KEYWORD,anthropic,claude-chain

要点：IP 不要频繁切换，CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 减少不必要的请求。

方案二：API 中转站

国内有不少 API 中转服务，无需代理即可直连：

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_API_KEY": "中转站 Key",
    "ANTHROPIC_BASE_URL": "https://你的中转站地址/"
  }
}

优点是简单，缺点是需要信任第三方、可能有延迟和稳定性问题。

方案三：AWS Bedrock / Google Vertex

适合企业用户，配置相对复杂，但合规性好。个人开发者一般用不到。

模型与价格怎么选

模型选择的经验法则：日常开发用 Sonnet 4（快、便宜、够强），遇到复杂架构设计或疑难 bug 切 Opus 4（最强推理能力）。

CLAUDE.md：效果提升的最高杠杆点

如果整篇文章你只记住一件事，记这个：写好 CLAUDE.md。

CLAUDE.md 是每次会话自动加载的项目配置文件，相当于给 AI 的入职手册。它告诉 Claude 你的项目是什么、怎么跑、有什么规矩。

四个核心原则

原则一：Less is More

研究数据显示，前沿模型可稳定遵循约 150-200 条指令，Claude Code 系统提示已占约 50 条。指令越多，遵循质量均匀下降。

HumanLayer 团队的 CLAUDE.md 只有不到 60 行。建议控制在 300 行以内，越短越好。

原则二：只写 Claude 猜不到的

✅ "Use Bun instead of Node"         — Claude 看不出你偏好 Bun
❌ "Use TypeScript"                   — 它看到 tsconfig.json 自己就知道

✅ "PR titles: feat|fix|chore: desc" — 具体的格式要求
❌ "Write clean code"                 — 太模糊，等于没说

原则三：渐进式披露

不要把所有知识塞进 CLAUDE.md，而是指向详细文档：

## Where to Find Things
- Architecture: docs/architecture.md
- Database: docs/database-schema.md
- API patterns: docs/api-patterns.md
Read relevant docs before starting tasks.

原则四：别当 Linter，用 Hook

格式化这种事，用 Hook 自动化，不要写在 CLAUDE.md 里浪费指令额度：

{
  "hooks": {
    "stop": [{
      "command": "npx biome check --apply .",
      "description": "Auto-format on stop"
    }]
  }
}

实战模板

直接拿去用：

# Project: [项目名]

## Stack
[技术栈一句话]

## Commands
- `npm run build` - Build
- `npm test` - Test
- `npm run lint` - Lint
- `npm run dev` - Dev server

## Code Rules
- [只写 Claude 猜不到的规则 1]
- [只写 Claude 猜不到的规则 2]

## Workflow
- Run single tests, not full suite (faster)
- Always typecheck after changes
- PR title format: feat|fix|chore: description

## Architecture
- /src/api — API routes
- /src/services — Business logic
- /src/db — Database

## Gotchas
- [项目里容易踩的坑]
- [非显而易见的行为]

配置层级

CLAUDE.md 支持三级加载，从通用到具体：

~/.claude/CLAUDE.md           ← 全局（所有项目通用偏好）
/project/CLAUDE.md            ← 项目级
/project/src/module/CLAUDE.md ← 模块级（特定子系统的规则）

高效工作流：从入门到飞起

1. Plan Mode：先想后做

Claude Code 有 Plan Mode（规划模式），适合复杂任务：

[Plan Mode] 探索代码库 → [Plan Mode] 制定方案 → [Normal Mode] 执行实现 → [Normal Mode] 提交

什么时候跳过？能一句话描述 diff 的小改动，直接做就行。

2. 给验证手段（最高杠杆技巧）

这是 Anthropic 官方反复强调的最重要技巧：告诉 Claude 怎么验证自己的工作。

❌ "fix the login bug"
✅ "users report login fails after session timeout. 
    check auth flow in src/auth/, especially token refresh.
    write a failing test, then fix it."

❌ "implement the design"
✅ "[paste screenshot] implement this design. 
    screenshot the result and compare."

关键是：给它具体的验证动作（跑测试、截图对比、构建验证），而不是让它自己判断”做完了”。

3. 上下文管理：保持 Claude 清醒

200K token 看似很多，实际可用约 155-167K（系统保留了缓冲区）。上下文膨胀后质量会下降。

4. Sub-agent 并行

Claude Code 支持子代理（Task 工具），可以并行处理互不依赖的任务：

并行条件：3+ 无关任务、无共享状态、文件不重叠
串行条件：有依赖关系、共享状态、范围不清
后台执行：研究型/分析型任务（不改文件的）

5. Slash Commands：把常用操作变成一键命令

在 .claude/commands/ 目录创建 Markdown 文件即可：

# .claude/commands/review.md
Review the current git diff. Check for:
- Error handling
- Type safety
- Test coverage
- Security issues
- Naming conventions

使用时输入 /review 即可触发。特别适合代码审查、发布检查等重复性工作。

Debug 和代码审查的实战技巧

Debug：像写 Bug Report 一样描述问题

❌ "fix the login bug"

✅ "users report login fails after session timeout.
    check auth flow in src/auth/, especially token refresh.
    write a failing test first, then fix it, 
    then verify the test passes."

要素：现象 → 可能范围 → 验证方式。越具体，Claude 越快定位。

代码审查：让 Claude 当你的 Reviewer

把 /review 命令配好之后，每次提交前跑一遍，Claude 会检查错误处理、类型安全、测试覆盖、安全问题和命名规范。比人工 review 快 10 倍，覆盖面更广。

重构：先测试后动手

1. 确保测试覆盖充分
2. 让 Claude 执行重构
3. 验证所有测试通过
4. 多个独立文件可以用子代理并行重构

安全：48% 的 AI 代码有漏洞

这不是危言耸听——研究数据显示 48% 的 AI 生成代码含安全漏洞。

必须人工审查的场景

• 认证/授权逻辑
• 支付处理
• 个人敏感信息（PII）处理
• 加密相关代码

权限配置建议

在 ~/.claude/settings.json 中明确 allow 和 deny：

{
  "permissions": {
    "allow": [
      "Bash(npm test)", "Bash(npm run lint)",
      "Bash(npm run build)", "Bash(git *)"
    ],
    "deny": [
      "Bash(rm -rf *)", "Bash(sudo *)"
    ]
  }
}

竞品快速对比

选择建议：

• 高级开发者，爱终端，想把任务委托给 AI → Claude Code
• 想要最好的编辑器内体验 → Cursor
• 大团队，合规优先 → Copilot
• 最佳组合：Claude Code（复杂任务）+ Cursor/VS Code（日常编辑）

快速上手检查清单

安装配置（30 分钟）

□ 安装 Claude Code
□ 配置代理环境变量
□ 订阅 Pro（$17/月）或配置 API Key
□ 配置 ~/.claude/settings.json（权限 + 环境变量）
□ 运行 claude --version 验证安装

项目配置（15 分钟）

□ 创建项目根目录 CLAUDE.md（控制在 60 行以内最佳）
□ 包含：技术栈、核心命令、代码规则、架构概览、Gotchas
□ 创建 .claude/commands/ 常用命令
□ 可选：配置 Hooks（自动格式化等）

日常使用习惯

□ 每个独立任务开新会话
□ 描述目标时给具体上下文和验证方式
□ 复杂任务用 Plan Mode 先规划
□ 主动 /compact 管理上下文
□ 敏感代码必须人工审查

写在最后

Claude Code 代表的不只是一个工具的升级，而是编程方式的范式转变——从”人写代码，AI 辅助”到”人定目标，AI 执行”。

但工具再强，核心还是你的判断力。知道什么该委托给 AI、什么必须自己把关，这才是 AI 时代开发者最重要的能力。

现在就去装一个试试。相信我，用过之后你会回不去的。

本文基于 Claude Code 官方文档、社区最佳实践及多源研究资料整理，数据截至 2026 年 4 月。

本文基于多源交叉验证的深度研究，带你拆解这个平台的架构、核心能力、竞品对比和战略意图。

一句话定位

从管理单个 AI 任务，转向委托完整的业务成果。

Gemini Enterprise Agent Platform 整合了 Google 在企业 AI 领域的三条产品线：

• Vertex AI（开发者平台）
• Gemini Enterprise App（企业员工入口）
• ADK（开源 Agent 开发框架）

形成 构建 → 扩展 → 治理 → 优化 的完整企业级 Agent 生命周期平台。

产品演进：18 个月改了 4 次名

坦率说，18 个月改了 4 次名，这品牌混乱度是减分项。但最终形态确实比之前清晰得多。

顶层架构：四大支柱

下面这张架构图展示了平台的完整分层设计：

四大支柱各司其职：

🔨 BUILD — 构建

ADK 是这里的明星产品。Apache 2.0 开源，15.6K Stars，700 万+ PyPI 下载——被称为”增长最快的 Agentic AI 框架”。一个最简 Agent 只需要几行代码：

from google.adk import Agent
from google.adk.tools import google_search

agent = Agent(
    name="researcher",
    model="gemini-flash-latest",
    instruction="You help users research topics thoroughly.",
    tools=[google_search],
)

🚀 SCALE — 扩展

• Agent Runtime：全托管运行时，亚秒级冷启动，支持长时间运行的 Agent（保持状态数天）
• Memory Bank：跨会话持久记忆
• Sessions：会话状态管理
• Cloud Run / GKE：灵活部署选项

🛡️ GOVERN — 治理

企业级治理三件套是 Google 的差异化重点：

加上 IAM 集成、VPC Service Controls、审计日志——这套安全体系的完整度在同类平台中领先。

📊 OPTIMIZE — 优化

• Agent Simulation：模拟用户交互，压力测试
• Agent Evaluation：多轮自动评分
• Agent Observability：运行时监控
• Trace Viewer：推理路径可视化

核心能力拆解

Agent 类型

多 Agent 编排

本地编排（ADK 内置）：Sequential / Parallel / Loop / Graph-based Workflow / Supervisor Pattern。

远程编排（A2A 协议）：Google 主导的跨 Agent 通信标准，支持不同框架（ADK、CrewAI、LangGraph）构建的 Agent 互相通信。已获 50+ 技术合作伙伴支持。

MCP 集成：Google Maps、BigQuery、Compute Engine、K8s Engine 等提供原生 MCP 服务器。

Grounding 与 RAG

• Google Search Grounding：实时网络搜索验证
• Enterprise Search Grounding：基于企业内部数据
• 60+ 第三方数据源：Confluence、SharePoint、Box、Jira、Salesforce、ServiceNow……
• 多模态 RAG：支持文档、图像、PDF

底层模型

Model Garden 提供 200+ 模型选择，这是 Google 的开放性优势。

竞品对比：五大平台横评

核心对局：Google vs Microsoft

• Microsoft 优势：全球 Office 365 用户基数、低代码体验更成熟、企业采购路径更短
• Google 优势：模型能力（上下文窗口 5x 于 GPT-4o）、开源框架、A2A 开放协议、多模型选择
• 关键差异：Microsoft 更适合已有 M365 生态的企业；Google 更适合多云策略和技术导向团队

个人判断：最终胜负取决于企业 IT 决策者选择”更封闭但更省事”还是”更开放但更需要投入”。

定价模型

Gemini Enterprise App（面向企业员工）

Agent Platform（面向开发者，按使用量计费）

免费额度：Express Mode 免费试用（最多 10 个 Agent Engine，90 天）；新用户 $300 免费额度。

按使用量计费对大规模部署有利（边际成本递减），但对中小企业的成本可预测性不友好。

开发者生态

GitHub 活跃度

ADK 2.0 Beta 已发布，新增 Workflow 支持和 Agent Teams 功能。ADK TypeScript 1.0 正式发布。

社区反馈

正面：

• 代码优先设计受开发者欢迎
• A2A 协议开放性获广泛支持
• 与 CrewAI、LangGraph 互操作性好
• Codelabs 学习资源质量高

待改进：

• 定价模型复杂，成本不易预测
• 品牌变更频繁造成混淆
• 低代码体验仍不如 Copilot Studio

客户案例

战略意图：Google 在想什么？

1. 云业务增长引擎

Agent Platform 是将 AI 模型优势转化为平台收入的关键。Google Cloud 需要差异化竞争对手 AWS 和 Azure。

2. “开放的围墙花园”策略

开源 ADK + 开放 A2A 协议吸引开发者，托管服务（Agent Engine、Memory Bank）创造平台粘性。比 Microsoft 的”闭源绑定”更有技术吸引力，但执行难度更大。

3. A2A 协议的标准化野心

类似当年 Kubernetes 的策略——开源一个标准，确保自己在标准制定中的主导地位。如果 A2A 成为事实标准，Google 将在多 Agent 时代占据有利位置。

4. 对抗 Microsoft Copilot

Microsoft 通过 M365 Copilot 占领企业 AI 入口，Google 必须有同等级别的回应。

关键洞察

1. 品牌整合信号战略聚焦：这不是改名，是 Google Cloud AI 从”模型即服务”到”Agent 即平台”的战略转型
2. ADK 开源策略正在奏效：15.6K Stars + 700 万下载量。护城河不在框架（可 fork），在托管服务
3. A2A 是长期赌注：50+ 合作伙伴是好的开始，但离事实标准还有距离
4. 定价是双刃剑：大规模部署有利，中小企业不友好

对企业的建议

风险提示

• 品牌混乱：18 个月内多次改名，客户和合作伙伴可能混淆
• 执行风险：Google 有”发布但不持续维护”的历史
• 模型竞争激烈：Gemini 的优势窗口可能很短

路线图推测

1. 所有 Vertex AI 服务完全迁移到 Agent Platform 品牌下
2. A2A 协议持续推动标准化（目标：Agent 通信的 HTTP）
3. 更多 MCP 服务器上线（Looker、Spanner 等）
4. ADK 2.0 正式版（预计 2026 Q2-Q3）
5. Agent Marketplace（企业级 Agent 市场）

结语

Gemini Enterprise Agent Platform 是 Google 在企业 AI 领域最完整的一次产品发布。四大支柱的设计清晰合理，ADK 的开源策略正在快速建立开发者生态，A2A 协议的标准化野心值得关注。

但品牌频繁变更、定价复杂性、以及 Google 在企业市场的历史执行力，都是需要持续观察的风险因素。

一句话总结：Google 正在用”开放 + 全栈”的策略对抗 Microsoft 的”生态 + 锁定”策略。谁赢还不好说，但企业客户多了一个高质量的选择。

数据来源：Google Cloud Blog、Forbes、TheNextWeb、GitHub、ADK 官方文档 (adk.dev)、Gartner、tech-insider.org 等。

研究时间：2026-04-27 · 研究员：黄山（wairesearch）· 编辑：五岳团队

研究员: 黄山 (wairesearch) 日期: 2026-04-25 时效性: 本报告数据截至 2026 年 4 月，AI Agent 领域发展迅速，建议 3 个月内复核关键结论

执行摘要

本报告系统调研了 AI Agent 自我进化领域的技术方案，重点分析了 Nous Research 的 Hermes Agent 自我改进机制，梳理了学术界和工业界的主流方案，并提出了 OpenClaw 落地自我进化能力的分阶段路径。

核心结论：

1. Hermes Agent 的”自我进化”本质是行为级/程序化记忆的闭环学习，不是模型权重的自我修改
2. 最可行的自我进化路径是技能自动创建/优化 + Prompt 进化 + 记忆自整理三位一体
3. OpenClaw 现有的技能系统 + 记忆系统已经具备基础框架，MVP 可在 2-4 周内落地
4. 学术界的 Symbolic Learning（符号学习）范式是最有前景的 Agent 自我进化理论框架

目录

1. Hermes 自我进化机制深度解析
2. AI Agent 自我进化主流方案
3. 关键论文与开源项目深度分析
4. OpenClaw 架构适配分析
5. 落地方案建议
6. 对比总表
7. 风险与限制
8. 参考来源

1. Hermes 自我进化机制深度解析

1.1 Hermes 的两层架构

Hermes 的”自我进化”分为两个层次，需要清晰区分：

关键洞察：老板提到的”对标 Hermes 的自我进化”，更准确地说是对标 Hermes Agent（Agent 层面的自我改进），而非模型训练层面的自我进化。这两者有本质区别。

1.2 Hermes 3 模型训练方法

根据 Hermes 3 Technical Report（arXiv:2408.11857）：

• 基础模型: 基于 Llama 3.1（8B/70B/405B）微调
• 训练数据: 主要是合成生成的响应数据（synthetically generated responses）
• 训练策略: 积极鼓励模型精确遵循 system prompt 和 instruction prompt
• Function Calling: 使用 <tools> 标签定义 schema，<tool_call> 和 <tool_response> 标签处理调用和返回
• RAG: 训练了 <co> 标签进行来源引用
• 数据集: 开源了 NousResearch/hermes-function-calling-v1 数据集

Hermes 模型系列演进：

• Hermes 3（2024.08）- 基于 Llama 3.1
• Hermes 4.3（2025）- 最新版本，支持 36B/70B/405B

1.3 Hermes Agent 的闭环学习循环（核心机制）

Hermes Agent（GitHub: NousResearch/hermes-agent）是 2025-2026 年发布的 Agent 框架，这才是我们要对标的核心。

四阶段学习循环

阶段 1: 任务执行 (Task Execution)
  → Agent 使用工具、编写代码、浏览网页、生成子 Agent
  
阶段 2: 自我评估检查点 (Self-Evaluation Checkpoint)
  → 每 15 次工具调用后自动暂停评估
  → 评估内容：做了什么？什么有效？什么失败了？值得记住吗？
  
阶段 3: 技能创建/更新 (Skill Creation or Update)
  → 如果经验值得保留，写入或更新技能文档
  → 使用 skill_manage 工具进行创建或 patch
  
阶段 4: 记忆更新 (Memory Update)
  → 关键事实、修正、惯例写入 MEMORY.md 和 USER.md
  → 在所有未来会话中可用

技能系统详解

• 格式: Markdown 文档，遵循 agentskills.io 开放标准
• 存储: ~/.hermes/skills/ 目录
• 结构: SKILL.md（主文档）+ references/（参考文档）+ templates/（模板）+ scripts/（脚本）
• 渐进式加载:
  • Level 0: skills_list() → 名称和描述（~3k tokens）
  • Level 1: skill_view(name) → 完整内容
  • Level 2: skill_view(name, path) → 特定参考文件

技能自我改进机制

# 创建新技能
skill_manage(action="create",
    name="competitor-analysis-workflow",
    content="# Competitor Analysis Workflow\n...")

# 更新已有技能（patch 模式）
skill_manage(action="patch",
    name="image-generation-branded",
    old_text="Logo opacity should be 70%",
    new_text="Logo opacity: 70% for dark backgrounds, 50% for light backgrounds (learned 2026-03-15)")

实际效果数据（来自用户报告）：

• 使用 20-30 个复杂任务后，Agent 行为发生质变
• 速度：第一周 25 次工具调用的任务，第六周降至 8-10 次
• 技能库：一个月后积累 10-40 个针对用户特定工作的技能

1.4 Hermes 的 Atropos RL 集成

Hermes Agent 还集成了 Nous Research 的 RL 训练管道：

• Atropos: Nous 的强化学习框架
• 轨迹生成: hermes batch --workers 4 --checkpoint ./training_data
• 数据导出: 支持 ShareGPT 格式，可用于微调
• 用途: 从真实 Agent 任务中生成 tool-calling 轨迹数据，用于训练下一代模型

这形成了一个大循环：

用户使用 Hermes Agent → 生成高质量轨迹数据 → 训练更好的模型 → 更好的 Agent 表现

1.5 HermesClaw 桥接

值得注意的是，Hermes Agent 已经提供了 OpenClaw 迁移工具（hermes claw migrate），并有一个 HermesClaw 社区桥接项目，允许在同一微信账号上同时运行 Hermes Agent 和 OpenClaw。

2. AI Agent 自我进化主流方案

2.1 技术分类框架

根据 EvoAgentX 团队 2025 年发布的综合调研（arXiv:2507.21046 & 2508.07407），Agent 自我进化可分为三大方向：

Agent 自我进化
├── 单 Agent 优化
│   ├── 推理能力进化（Reasoning Evolution）
│   ├── Prompt/指令进化（Prompt Evolution）
│   ├── 工具使用进化（Tool Use Evolution）
│   └── 记忆系统进化（Memory Evolution）
├── 多 Agent 优化
│   ├── 工作流自动构建（Workflow Autoconstruction）
│   ├── Agent 间协作进化（Inter-agent Evolution）
│   └── 角色/分工进化（Role Evolution）
└── 领域特定优化
    ├── 代码生成（Code Generation）
    ├── 数学推理（Mathematical Reasoning）
    └── 科学发现（Scientific Discovery）

2.2 六大核心范式

2.3 AutoGPT / BabyAGI 的教训

早期自主 Agent 的尝试给出了重要教训：

核心教训：纯自主的自我进化容易失控。成功的方案都有评估反馈机制和人类监督通道。

3. 关键论文与开源项目深度分析

3.1 Reflexion: Language Agents with Verbal Reinforcement Learning

• 论文: arXiv:2303.11366（NeurIPS 2023）
• 作者: Noah Shinn et al.
• GitHub: noahshinn/reflexion — ⭐ ~2.3k Stars
• 核心机制:
  • Agent 执行任务后进行自我反思，生成文本形式的反馈
  • 反馈存入短期记忆（当前轨迹）和长期记忆（蒸馏后的反思）
  • 下次尝试时，将之前的反思作为上下文
  • 在 AlfWorld（134→97%）、HotPotQA、HumanEval（67→91%）上大幅提升
• 对 OpenClaw 的启发:
  • 每次任务失败后自动生成反思文本
  • 反思存入记忆系统，下次类似任务时自动检索

3.2 Self-Refine: Iterative Refinement with Self-Feedback

• 论文: arXiv:2303.17651（NeurIPS 2023）
• 作者: Aman Madaan et al.
• GitHub: madaan/self-refine — ⭐ ~1.5k Stars
• 核心机制:
  • 三步循环：生成（Generate）→ 反馈（Feedback）→ 修正（Refine）
  • 不需要额外训练或监督信号
  • 在 7 个任务上平均绝对提升 20%
  • 大部分增益在前 1-2 轮迭代
• 对 OpenClaw 的启发:
  • Agent 输出后进行自我评估，生成改进建议
  • 特别适合代码生成、文档写作等可迭代优化的任务

3.3 Voyager: An Open-Ended Embodied Agent with LLMs

• 论文: arXiv:2305.16291（NeurIPS 2023 Spotlight）
• 作者: Guanzhi Wang et al.（NVIDIA）
• GitHub: MineDojo/Voyager — ⭐ ~5.7k Stars
• 核心机制:
  1. 自动课程（Automatic Curriculum）: 最大化探索的任务自动生成
  2. 不断增长的技能库（Ever-growing Skill Library）: 可执行代码存储和检索复杂行为
  3. 迭代提示（Iterative Prompting）: 结合环境反馈、执行错误的多轮代码精炼
  4. 自我验证（Self-Verification）: 任务完成前自动检查
• 关键数据: 获取 3.3x 更多物品、行走 2.3x 更远、解锁科技树快 15.3x
• 对 OpenClaw 的启发:
  • 技能库模式是核心：OpenClaw 的技能系统天然对应 Voyager 的 Skill Library
  • 自动课程 → 可以在 cron 任务中设计自我探索任务
  • 迭代提示 + 环境反馈 → 技能执行失败时自动修复

3.4 Symbolic Learning Enables Self-Evolving Agents（Agents 2.0）

• 论文: arXiv:2406.18532（2024）
• 作者: Wangchunshu Zhou et al.（aiwaves-cn）
• GitHub: aiwaves-cn/agents — ⭐ ~5.9k Stars
• 核心机制:
  • 将 Agent 管道类比为神经网络的计算图
  • Agent 管道中的节点 ↔ 神经网络中的层
  • 节点的 Prompt 和工具 ↔ 层的权重
  • 实现了语言损失函数、反向传播、梯度下降的符号版本
  • 前向传播（Agent 执行）→ 语言损失评估 → 语言梯度反向传播 → 符号组件更新
• 关键创新:
  • 不修改模型权重，而是用自然语言实现了类似梯度下降的优化过程
  • 支持多 Agent 系统的联合优化
• 对 OpenClaw 的启发:
  • 这是目前最优美的理论框架
  • OpenClaw 的多 Agent 架构（main/waicode/wairesearch 等）可以映射为计算图
  • 每个 Agent 的 SOUL.md、Prompt 模板可以通过”语言梯度”自动优化

3.5 EvoAgentX: Building a Self-Evolving Ecosystem of AI Agents

• 论文: arXiv:2507.03616（EMNLP 2025 Demo）
• 调研论文: arXiv:2508.07407（Comprehensive Survey of Self-Evolving Agents）
• GitHub: EvoAgentX/EvoAgentX — ⭐ ~1,000+ Stars（2025.07 达成）
• 核心机制:
  1. 工作流自动构建: 从自然语言目标自动生成多 Agent 工作流
  2. 内置评估: 自动评估器按任务特定标准打分
  3. 自进化引擎: 使用自进化算法改进工作流
  4. 记忆模块: 短期 + 长期记忆系统
  5. 人在回路: 支持人类审核、修正、引导
• 对 OpenClaw 的启发:
  • 工作流自动构建 → OpenClaw 可以根据用户需求自动编排 Agent 协作
  • 评估 + 进化引擎 → 可以评估每个 Agent 的 SOUL.md 效果并自动优化

3.6 其他重要工作

4. OpenClaw 架构适配分析

4.1 OpenClaw 当前架构

OpenClaw 架构
├── 多 Agent 协调
│   ├── main（协调者）
│   ├── wairesearch（研究）
│   ├── waicode（开发）
│   ├── bizstrategy（商业）
│   ├── product（产品）
│   └── growth（增长）
├── 技能系统（Skills）
│   ├── ~/.openclaw/skills/ 目录
│   ├── SKILL.md 标准格式
│   ├── 渐进式加载
│   └── 技能分类和路由
├── 记忆系统（Memory）
│   ├── MEMORY.md（持久化记忆）
│   ├── USER.md（用户档案）
│   ├── lossless-claw（会话压缩/检索）
│   └── memory-wiki（知识库）
├── Context 文件
│   ├── SOUL.md（角色人格）
│   ├── AGENTS.md（Agent 配置）
│   ├── IDENTITY.md（身份定义）
│   └── TOOLS.md（工具配置）
├── Cron 任务
│   └── 定时自动化
└── 消息网关
    └── Telegram / 其他平台

4.2 自我进化维度与实现层次分析

4.3 OpenClaw vs Hermes Agent 能力对比

4.4 OpenClaw 独有优势

1. 多 Agent 团队架构: OpenClaw 有成熟的专家 Agent 团队（研究/开发/商业/产品/增长），Hermes 目前主要是单 Agent + 子 Agent 模式
2. 角色系统: SOUL.md 提供了丰富的人格和行为规范，为 Prompt 进化提供了天然的优化目标
3. 记忆系统: lossless-claw 的会话压缩和跨会话检索已经很成熟
4. 工作流编排: 协调者-专家模式天然适合工作流优化

5. 落地方案建议

5.1 分阶段实施路径

Phase MVP（2-4 周）: 自我评估 + 技能自动创建

目标: 让 OpenClaw 能自动从经验中创建和改进技能

实现方案:

1. 自我评估检查点（仿 Hermes 的 15-step checkpoint）
   → 在 Agent 执行每 N 次工具调用后，插入评估 Prompt
   → 评估 Prompt: "过去 N 步中，你做了什么？什么有效？什么值得记为技能？"
   → 实现方式: 在 main Agent 的系统 Prompt 中添加自评估规则

2. skill_manage 工具
   → 创建 skill_manage(action, name, content, old_text, new_text) 工具
   → action: create / patch / delete / list
   → 技能自动保存到 ~/.openclaw/skills/auto-generated/
   → 实现方式: 新建一个技能（meta-skill），教 Agent 如何创建技能

3. 记忆 nudge 机制
   → 在自评估检查点中，同时检查是否有值得持久化的信息
   → 提示 Agent 主动更新 MEMORY.md

技术选型:

• 无需底层改动，全部通过新技能 + Prompt 工程实现
• 创建 self-evolution 技能目录，包含自评估和技能管理的 SKILL.md

预计产出:

• 使用 20+ 复杂任务后，自动积累 5-15 个技能
• 重复任务的效率提升 30-50%（参考 Hermes 用户数据）

Phase V1（1-2 月）: Prompt 进化 + 工作流优化

目标: Agent 能自动优化自己的 SOUL.md 和工作流

实现方案:

1. Prompt 自我优化
   → 参考 GEPA（Reflective Prompt Evolution）和 OPRO
   → 每周/每月通过 cron 任务触发 Prompt 优化评估
   → 分析最近 N 次任务的成功率和效率
   → 生成 SOUL.md 的优化建议，需人工确认后生效
   → 实现方式: 新建 prompt-evolution 技能

2. 工作流评估与优化
   → 记录多 Agent 协作的任务轨迹
   → 分析哪些 Agent 协作模式效果好/差
   → 自动建议工作流调整（如：某类任务应直接分配给 waicode 而非先经过 wairesearch）
   → 实现方式: 在 main Agent 中增加工作流评估逻辑

3. 错误模式学习
   → 记录任务失败的原因和修复方式
   → 类似 Reflexion 的反思机制
   → 失败→反思→记忆→下次避免
   → 实现方式: 增加 error-reflection 技能

技术选型:

• GEPA（arXiv:2507.19457）的 Reflective Prompt Evolution 方法，效果已被证明超过 RL
• DSPy 的多阶段优化思想
• 可能需要小幅修改 Agent 配置加载逻辑（支持 A/B 测试不同 SOUL.md）

Phase V2（3-6 月）: 符号学习 + 自进化生态

目标: 建立完整的自进化生态系统

实现方案:

1. 符号学习框架
   → 参考 aiwaves-cn/agents 的 Symbolic Learning
   → 将多 Agent 管道建模为计算图
   → 实现"语言梯度"的反向传播
   → 自动优化每个 Agent 的 Prompt、工具选择、协作模式

2. 技能市场
   → 参考 Hermes 的 agentskills.io 和技能分享机制
   → 用户间共享经过验证的技能
   → 技能评分和推荐系统

3. 自进化 Dashboard
   → 可视化展示进化过程
   → 技能创建/使用频率统计
   → Prompt 优化历史
   → 工作流效率趋势

4. RL 数据生成（可选）
   → 类似 Hermes 的 Atropos 集成
   → 从用户交互中生成高质量训练数据
   → 用于微调自有模型或贡献给社区

技术选型:

• aiwaves-cn/agents 2.0 的 Symbolic Learning 框架
• TextGrad（arXiv:2406.07496）的”文本自动微分”思想
• EvoAgentX 的工作流自动构建 + 评估方法

5.2 MVP 具体实现方案

方案 A: Pure Prompt Engineering（推荐）

完全通过技能和 Prompt 实现，零代码改动：

# 创建技能: ~/.openclaw/skills/self-evolution/SKILL.md

## 自评估规则
在完成复杂任务后（使用了 10+ 次工具调用），执行以下自评估：

1. 回顾本次任务的执行过程
2. 识别可复用的工作流模式
3. 如果发现值得保留的模式：
   - 在 ~/.openclaw/skills/auto/ 目录创建新技能
   - 或更新已有技能
4. 将关键发现写入 MEMORY.md

优点:

• 开发成本极低（1-2 天）
• 不需要底层改动
• 立即可用

缺点:

• 依赖 LLM 自觉性，可能不稳定
• 无法精确控制触发时机

方案 B: 轻量级工具扩展

增加 skill_manage 和 self_evaluate 工具：

// skill_manage 工具
interface SkillManageParams {
  action: 'create' | 'patch' | 'delete' | 'list';
  name: string;
  content?: string;
  old_text?: string;
  new_text?: string;
}

// self_evaluate 工具（在 N 步后自动调用）
interface SelfEvaluateParams {
  recent_actions: string[];  // 最近 N 步的动作摘要
  task_outcome: 'success' | 'partial' | 'failure';
}

优点:

• 更精确的控制
• 可以记录评估数据用于后续分析
• 更好的用户体验

缺点:

• 需要少量开发工作（3-5 天）
• 需要修改 OpenClaw 的工具注册机制

推荐: 方案 A 快速验证 → 方案 B 正式实现

5.3 技术选型建议

6. 对比总表

6.1 自我进化框架对比

6.2 GitHub 项目数据

注：Stars 数据为 2026 年 4 月估计值，实际数据可能有波动

7. 风险与限制

7.1 技术风险

7.2 实施风险

7.3 已知限制

1. LLM 底座不变: 所有”进化”都是在 Agent 行为层面，底层 LLM 的能力上限不变
2. 领域特定: 自我进化只在用户实际使用的领域有效，不会泛化到未接触领域
3. 冷启动: 新用户/新领域需要经历学习期（20-30 个任务）
4. Token 成本: 自评估检查点会增加 token 消耗（估计增加 10-15%）

8. 参考来源

论文

1. Hermes 3 Technical Report — Ryan Teknium et al., 2024. arXiv:2408.11857
2. Reflexion: Language Agents with Verbal Reinforcement Learning — Noah Shinn et al., NeurIPS 2023. arXiv:2303.11366
3. Self-Refine: Iterative Refinement with Self-Feedback — Aman Madaan et al., NeurIPS 2023. arXiv:2303.17651
4. Voyager: An Open-Ended Embodied Agent with Large Language Models — Guanzhi Wang et al., NeurIPS 2023. arXiv:2305.16291
5. Symbolic Learning Enables Self-Evolving Agents — Wangchunshu Zhou et al., 2024. arXiv:2406.18532
6. EvoAgentX: An Automated Framework for Evolving Agentic Workflows — Yingxu Wang et al., EMNLP 2025. arXiv:2507.03616
7. A Survey of Self-Evolving Agents: On Path to ASI — Huan-ang Gao et al., 2025. arXiv:2507.21046
8. A Comprehensive Survey of Self-Evolving AI Agents — EvoAgentX Team, 2025. arXiv:2508.07407
9. Promptbreeder: Self-Referential Self-Improvement Via Prompt Evolution — ICML 2024. arXiv:2309.16797
10. TextGrad: Automatic “Differentiation” via Text — 2024. arXiv:2406.07496
11. Large Language Models as Optimizers (OPRO) — ICLR 2024. arXiv:2309.03409
12. GEPA: Reflective Prompt Evolution Can Outperform RL — 2025. arXiv:2507.19457

GitHub 项目

1. NousResearch/hermes-agent — Hermes Agent 框架
2. NousResearch/Hermes-Function-Calling — Hermes Function Calling
3. MineDojo/Voyager — Voyager Agent
4. aiwaves-cn/agents — Agents 2.0 (Symbolic Learning)
5. EvoAgentX/EvoAgentX — EvoAgentX 框架
6. EvoAgentX/Awesome-Self-Evolving-Agents — 自进化 Agent 综合列表
7. CharlesQ9/Self-Evolving-Agents — 自进化 Agent 调研
8. noahshinn/reflexion — Reflexion
9. madaan/self-refine — Self-Refine
10. stanfordnlp/dspy — DSPy 框架
11. zou-group/textgrad — TextGrad

官方文档

1. Hermes Agent Documentation
2. Hermes Agent Skills System
3. Self-Improving AI — The Hermes Feature That Actually Works
4. Nous Research - Hermes 3
5. agentskills.io Standard

研究完成时间: 2026-04-25 23:30 CST 研究员: 黄山 (wairesearch) 下一步建议: 将本报告转交 waicode 进行 MVP 原型开发

执行摘要

Hermes Agent 是 Nous Research 开发的开源自进化 AI Agent 框架（GitHub 90k+ Stars，MIT 协议）。在上一篇文章中，我们拆解了它的自动 Skill 创建机制。今天我们深入另一个核心模块——记忆系统。

Hermes 的记忆架构分为三层内建记忆 + 外部记忆提供者插件，选择了 SQLite FTS5 而非向量数据库作为核心检索方案。这是一个务实且高效的设计选择，解决了 AI Agent 最基本的问题：失忆。

Hermes Agent 快速回顾

核心理念很简单：传统 Agent 每次对话后遗忘一切，而 Hermes 通过持久化记忆 + 自动技能提炼，实现经验的累积和复用。

记忆系统架构总览

Hermes 的记忆系统是分层 + 可插拔的设计，我们可以把它想象成一栋楼：

┌──────────────────────────────────────────┐
│          Always Active（内建）             │
│                                          │
│  Layer 1: 冻结系统提示记忆                 │
│    MEMORY.md + USER.md                   │
│    → 每次会话注入 system prompt            │
│                                          │
│  Layer 2: 程序性技能记忆                   │
│    ~/.hermes/skills/*.skill              │
│    → agentskills.io 开放标准              │
│                                          │
│  Layer 3: 会话搜索                        │
│    SQLite FTS5 全文索引                    │
│    → LLM 摘要化检索结果                    │
└──────────────────────────────────────────┘
                    +
┌──────────────────────────────────────────┐
│     Optional（外部记忆提供者，8 选 1）      │
│  Honcho / OpenViking / Mem0 / Hindsight  │
│  Holographic / RetainDB / ByteRover ...  │
└──────────────────────────────────────────┘

三条核心设计哲学：

1. 内建记忆永远在线，外部提供者是加法，不替代
2. 冻结快照模式：记忆在会话开始时注入 system prompt，会话中修改立即写盘但不更新 prompt（为了保护 LLM prefix cache 性能）
3. 容量刻意有限：memory 2,200 chars + user 1,375 chars ≈ ~1,300 tokens，逼迫 Agent 策展高质量记忆

Layer 1: 冻结系统提示记忆

这是 Hermes 记忆的”基石层”，分为两个文件：

MEMORY.md 是 Agent 的个人笔记本（2,200 chars 上限），用来记录环境信息、项目上下文、经验教训。USER.md 是用户画像（1,375 chars 上限），记录你的偏好、沟通风格和常用工具。

两者在每次会话开始时冻结注入 system prompt，Agent 直接”看到”，无需主动读取。

操作机制

Agent 通过三个操作管理记忆：

• add：添加新条目
• replace：通过子串匹配替换（不需要完整文本，唯一子串就够了）
• remove：通过子串匹配删除

注意没有 read 操作——因为记忆已经在 system prompt 里了。

容量管理的艺术

超过 80% 容量时，Agent 会主动合并压缩条目。满了就返回错误，Agent 必须先清理再添加。系统还内置了自动去重和注入安全扫描（防 prompt injection）。

记忆条目用 § 分隔，头部显示使用百分比：

═══════════════════════════════════════════
MEMORY [67% — 1,474/2,200 chars]
═══════════════════════════════════════════
User's project is a Rust web service using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker installed
§
User prefers concise responses

什么该存：用户偏好、环境事实、项目约定、经验教训、修正纠错。

什么不该存：琐碎信息、可搜索的通用知识、大段代码/日志、临时会话信息。

Layer 2: 程序性技能记忆

技能系统是 Hermes 最核心的创新——将任务执行经验提炼为可复用的代码单元。关于这部分的详细分析，请参考我们的上一篇文章。

简单来说，Agent 完成复杂任务后会自动分析执行步骤，抽象为可复用模式，保存为 .skill 文件。后续遇到类似任务时，通过语义匹配召回最相关技能。每次执行后还会记录成功/失败，持续优化。

技能存储在 ~/.hermes/skills/，遵循 agentskills.io 开放标准。

Layer 3: 会话搜索（SQLite FTS5）

第三层是对历史会话的全文搜索能力。Hermes 用 SQLite FTS5 虚拟表索引所有过去的会话：

CREATE VIRTUAL TABLE conversation_fts USING fts5(
    content, speaker, timestamp, session_id
);

检索流程很直接：查询触发 → FTS5 匹配 → 结果经 LLM 摘要化 → 注入当前上下文。

为什么选 FTS5 而非向量数据库？

这是一个很多人会问的问题。Hermes 的选择很务实：

FTS5 的优势：零运维（SQLite 内建）、精确匹配出色（人名、项目名、命令不会丢）、本地部署友好（$5 VPS 就能跑）、完全免费。

向量数据库的优势：原生语义搜索能力更强。

Hermes 的解法：用 LLM 摘要层补偿 FTS5 的语义短板。搜索结果先经过全文匹配拿到高精度候选，再用 LLM（默认 Gemini Flash）做语义理解和摘要。

这个”土方法”在实际使用中效果很好——精确匹配保证不丢关键信息，LLM 摘要补偿语义理解，两者结合比纯向量检索更可靠。

外部记忆提供者：8 选 1 的插件体系

除了三层内建记忆，Hermes 还支持 8 个外部记忆提供者插件（同时只能激活一个）。

Honcho：辩证用户建模

Honcho 是 Hermes 最深度集成的记忆提供者，由 Plastic Labs 开发。它的核心创新是辩证用户建模——不仅记住你说了什么，还推理你是怎么思考的。

Honcho 的上下文注入分两层：

基础层（Base Context） 包含会话摘要、用户表征、AI 自我表征等，按 contextCadence 参数控制刷新频率。

辩证补充层（Dialectic Supplement） 通过 LLM 多轮推理合成用户当前状态和需求：

三个调节旋钮让你精细控制成本和效果：contextCadence（基础层刷新频率）、dialecticCadence（辩证调用频率）、dialecticDepth（推理深度 1-3）。

Honcho 还支持 Multi-Peer 架构：同一用户可以有不同的 AI Peer（编码、写作等），每个 Peer 独立构建用户表征，互不污染。

其他提供者一览

其中 RetainDB、ByteRover、Supermemory 截至研究时尚无公开详细文档。

与主流记忆系统的对比

Hermes 的五大独特创新

1. 闭环技能学习：唯一实现”任务→技能提炼→优化→社区共享”完整闭环的框架
2. 辩证用户建模：Honcho 不仅记住你说了什么，还推理你的思维模式
3. 刻意有限的核心记忆：2,200+1,375 chars 硬上限是设计选择，逼迫 Agent 像人类一样策展
4. FTS5 + LLM 摘要：务实的检索方案，零运维，精确匹配不丢信息
5. RL 飞轮：Agent 执行轨迹 → 训练数据 → 更好的模型 → 更好的 Agent

实际应用场景

• 个人 AI 助手：长期使用，Agent 越来越了解你的偏好和工作方式
• DevOps 自动化：部署流程自动提炼为可复用技能，越用越顺
• 多平台统一入口：Telegram 开始任务，CLI 继续，Agent 保持上下文
• 团队技能共享：通过 agentskills.io 标准跨团队复用 Agent 技能

已知局限性

值得注意的是，这套系统也有明显的短板：

• 核心记忆容量极小：2,200+1,375 chars 对于复杂项目可能不够，需依赖外部提供者补充
• FTS5 缺乏语义搜索：同义词、概念关联搜索弱于向量数据库，LLM 摘要层是补丁而非原生方案
• 外部提供者单选：同时只能激活一个外部记忆提供者，无法混合使用
• Honcho 外部依赖：辩证用户建模是最强功能，但需要 Honcho Cloud 或自托管实例
• 冻结快照延迟：会话中更新的记忆需要下一次会话才生效

独立评价

Hermes 的记忆系统体现了”务实工程”而非”论文驱动”的思路。 FTS5 + LLM 摘要的组合看似”土”，但解决了几个实际痛点：零运维、精确匹配、轻量部署。这是面向个人用户和小团队的正确选择。

冻结快照模式是被低估的优秀设计。 它牺牲实时性（记忆更新延迟一个会话），换取 LLM prefix cache 的性能收益。在高频对话场景中，这个优化非常实际。

技能学习系统是真正的差异化壁垒。 MemGPT、LangChain、LlamaIndex 都有记忆方案，但没有人做到完整的闭环技能学习。

对 OpenClaw 的启示

有趣的是，Hermes 和 OpenClaw 的记忆系统高度相似（MEMORY.md、FTS5、冻结快照），这不是巧合——Hermes 官方支持从 OpenClaw 迁移。核心差异在于：

• Hermes 有技能自动提炼（OpenClaw 需手动编写 SKILL.md）
• Hermes 有 Honcho 辩证用户建模（OpenClaw 无对等方案）
• OpenClaw 有 lossless-claw 无损压缩回忆（Hermes 无对等方案）

两者各有取舍，共同推动着 AI Agent 记忆系统的工程实践向前发展。

参考来源

1. Hermes Agent 官方文档 - Memory
2. Hermes Agent 官方文档 - Memory Providers
3. Hermes Agent 官方文档 - Honcho
4. GitHub - NousResearch/hermes-agent
5. DEV.to - Hermes Agent 深度分析
6. MarkTechPost - Hermes Agent Release
7. Vectorize.io - How Hermes Agent Memory Works

基于 OpenClaw v2026.4.12 源码 + 官方文档 + GitHub Issues

执行摘要

如果你用过 OpenClaw 一段时间，大概率遇到过这个场景：Bot 显示”输入中”，然后……就没有然后了。

这篇文章系统分析了 OpenClaw Session 的状态管理机制，梳理了 7 种已确认的 Stuck 模式和 3 种死锁场景，并提供了一份实用的排查手册。无论你是 OpenClaw 的日常用户还是深度定制者，这篇都能帮你理解”为什么 Bot 会卡住”以及”怎么快速恢复”。

Session 状态管理机制

完整生命周期

一条消息从发出到得到回复，经过以下流程：

消息到达 → 路由(sessionKey) → 入队(Command Queue) → 获取 Session 锁
    → 加载 SessionManager → 构建 System Prompt → LLM 推理
    → 工具执行 → 流式回复 → Compaction 检查 → 释放锁 → 排队下一个

状态机模型如下：

                    ┌──────────┐
    新消息到达 ──→  │  queued   │  ← 在 Command Queue 等待
                    └────┬─────┘
                         │ lane 空闲，获取 session 写锁
                         ▼
                    ┌──────────┐
                    │ running   │  ← LLM 推理 + 工具执行
                    └────┬─────┘
                         │
              ┌──────────┼──────────┐
              │          │          │
              ▼          ▼          ▼
         ┌────────┐ ┌────────┐ ┌────────┐
         │complete│ │aborted │ │ error  │
         └────────┘ └────────┘ └────────┘
              │          │          │
              └──────────┴──────────┘
                         │
                    Compaction（可选）→ 释放锁

两层持久化架构

三层并发控制

OpenClaw 使用三层机制防止并发冲突：

1. Command Queue（Lane 系统）：main（入站消息，并发上限 4）、subagent（子 Agent，上限 8）、cron（定时任务）、nested（嵌套调用），每个 session 同一时间只有一个 active run。

2. Session 文件锁：.jsonl.lock 锁文件，超时 10 秒。

3. Gateway 进程级隔离：单进程模型，restart 时有 30 秒 drain 机制。

7 种 Stuck 模式

通过分析 GitHub Issues 和源码，我们确认了以下 7 种 Session 卡死模式：

模式 1：LLM API 流式挂起 — 最高频 🔴

Issue: #17258

上游 LLM API 接受了流式请求但不产生任何 token。HTTP 连接保持打开，系统一直等到绝对超时（默认 600s）。

T+0s    流式请求开始，API 返回 HTTP 200
T+2s    ...静默，无 token 到达...
T+120s  Typing indicator 过期，用户看到 Bot "离线"
T+300s  超时触发，session abort

解决方案：v2026.2.x 引入了 llm.idleTimeoutSeconds，建议设为 90 秒。

模式 2：Compaction 死循环 + 锁文件残留 🔴

Issue: #21621

Browser Tool 执行后触发 compaction，compaction 进入 retry 循环永不完成。关键特征：日志中有 compaction retry 但没有 embedded run done。

模式 3：Gateway 自请求死锁 🔴

Issue: #18470

Agent 在 active turn 中调用 openclaw sessions --json → CLI 需要查询 Gateway → Gateway 在等 agent turn 完成 → 经典死锁。

模式 4：Session 文件锁超时 🟡

Issue: #31489

.jsonl.lock 文件因崩溃残留，10 秒后锁获取失败，agent 无法回复。

模式 5：Gateway Restart 时 Compaction 中断 🟡

Issue: #17635

config.apply 触发 SIGUSR1 restart，但 30 秒 drain timeout 不够 compaction 完成。

模式 6：Context 超限导致 Compaction 死循环 🔴

Issue: #25620

Context 超过模型 token 限制 → /compact 的 summarization 请求本身也超限 → 无法压缩 → 死循环。

模式 7：工具调用失败无恢复 🔴

Issue: #8288

工具调用挂起后无超时、无恢复、无 fallback。唯一恢复方式是 /new 或 /reset，但会丢失全部上下文。

Stuck 原因分类汇总

3 种死锁场景

死锁经典四条件

死锁 1：Gateway 自请求死锁

┌──────────────┐          ┌──────────────┐
│ Agent Turn   │ ──等待─→ │ 内部命令     │
│ (lane 被占)  │          │ (需查 Gateway)│
│              │ ←─阻塞── │              │
└──────────────┘          └──────────────┘

Agent 通过 exec 调用 openclaw CLI，CLI 需通过 WebSocket 查询 Gateway，但 Gateway 被 active session lane 阻塞。

死锁 2：Compaction Lock 死锁

Compaction 过程中 Gateway crash → lock 文件残留 → 所有后续操作 10 秒超时失败。

死锁 3：Compaction 超限悖论

Context 过大 → 触发 Compaction → summarization 也超限 → 失败 → 仍然过大 → 循环

排查手册

症状速查表

手动恢复命令

# 1. 检查 session 状态
openclaw sessions --json
openclaw sessions --active 120

# 2. 在 chat 中重置
/stop             # 停止当前 agent run
/new              # 新建 session
/reset            # 重置当前 session

# 3. 清除锁文件（确保无活跃 run）
ls ~/.openclaw/agents/*/sessions/*.lock
rm -f ~/.openclaw/agents/*/sessions/*.lock

# 4. 重启 Gateway
openclaw gateway restart

# 5. Session 清理
openclaw sessions cleanup --dry-run
openclaw sessions cleanup --enforce

# 6. 核弹选项（完整重置）
openclaw reset --scope config+creds+sessions --yes

日志关键词速查

grep -i "stuck\|timeout\|abort\|compaction retry\|lock\|deadlock\|drain" \
  ~/.openclaw/logs/*.log

推荐配置调优

以下配置可显著降低 Stuck 发生概率：

{
  agents: {
    defaults: {
      // 从默认 48h 缩短到 30min
      timeoutSeconds: 1800,
      llm: {
        // API 90s 无响应则中止
        idleTimeoutSeconds: 90,
      },
      compaction: {
        enabled: true,
        reserveTokens: 20000,
        reserveTokensFloor: 20000,
        memoryFlush: { enabled: true, softThresholdTokens: 4000 },
      },
    },
  },
  session: {
    maintenance: {
      mode: "enforce",
      pruneAfter: "30d",
      maxEntries: 500,
    },
    reset: {
      idleMinutes: 120,  // 2h 无活动自动重置
    },
  },
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
    },
  },
}

预防最佳实践

1. 避免 Agent Turn 中调用内部 CLI 命令 — 改用 session_status 等内部 RPC 工具
2. 设置合理超时 — timeoutSeconds: 1800，idleTimeoutSeconds: 90
3. 监控 lock 文件 — 定期检查并清除超过 5 分钟的 .lock 文件
4. 用 systemd/launchd 监管 Gateway — 异常退出自动重启
5. 开启 memoryFlush — 压缩前保存关键上下文
6. Sub-agent 用 sessions_yield — 不要 poll 循环等待

架构洞察

通过这次分析，我们发现几个值得关注的架构层面问题：

1. 默认 48h 超时是 Stuck 的放大器 — 即使出了问题，系统也要等很久才超时。缩短到 30 分钟可以显著改善用户体验。

2. 自请求死锁是设计缺陷 — Agent 能通过 exec 调用 openclaw CLI 并触发 Gateway 自查询，形成循环依赖。应在架构层面让内部命令走独立通道。

3. 文件锁机制脆弱 — 基于文件锁的并发控制在进程崩溃时必然残留。建议改为带 PID + 时间戳的锁，或在单进程架构下使用进程内锁。

4. Compaction 是高频触发器 — 多个 Issue 都与 compaction 相关，它涉及 LLM 调用 + 文件锁 + retry，任一环节卡住都导致 session 不可用。

5. 缺少主动死锁检测 — 建议添加 session 活跃时间 watchdog、lock 文件 TTL、自请求检测等机制。

相关 GitHub Issues

总结

Session Stuck 和死锁是 OpenClaw 用户最常遇到的痛点之一。理解其背后的状态机模型、并发控制机制和已知的 7 种 Stuck 模式，能帮助你在问题发生时快速定位和恢复。更重要的是，通过合理的配置调优和最佳实践，大部分 Stuck 问题可以被预防。

记住这个优先级：先 /stop，再看 lock 文件，最后 restart Gateway。大多数情况下，前两步就能解决问题。

作者：小帅（Team Commander）| 日期：2026-04-23 | 状态：Proposal v2 | 优先级：P0
基于：OpenClaw 2026.4.12 源码（GitHub main 6b126cd）+ 社区调研

v1 → v2：为什么要重写？

v1 的错误

早上写 v1 方案时，我们基于推测性分析得出结论：「OpenClaw 没有任何防护机制，需要从头写 ~600 行代码实现 Supervisor + Guard 双层防御」。

这个结论是错的。

下午深入 OpenClaw GitHub 源码后发现：OpenClaw 已经内建了完整的 transcript repair 机制，包括缺失 tool result 的自动合成、重复 result 去重、孤立 result 丢弃、位移 result 重排。我们在 v1 中提出的「方案 B：Conversation State Guard」，OpenClaw 早就实现了。

v2 的态度

先看源码，再提方案。 这是工程师的基本功，v1 犯了「先入为主、推测先行」的错误。v2 基于源码实证，明确了已有防护和真正的盲区，方案也从「大兴土木」变为「配置调优 + 精准补齐」。

问题定义

现象

Session 在 LLM 发出 tool_call 后卡死，无法接收新消息，用户只能手动 /kill 或 /reset。

协议约束

LLM 对话协议的不可违反约束：每个 tool_call 必须有且仅有一个对应的 tool_result。 缺少 tool_result 时，对话状态非法，LLM 无法继续推理。

丢失 tool_result 的 5 种根因

OpenClaw 已有防护机制（源码实证）

这是 v2 最重要的新增章节。以下所有结论均来自 OpenClaw GitHub main 分支 6b126cd 的源码阅读。

Transcript Repair — 合成缺失 Tool Result

源码位置：src/agents/session-transcript-repair.ts

OpenClaw 已经实现了 repairToolUseResultPairing 函数，在构建 LLM 上下文时自动修复缺失的 tool result：

// src/agents/session-transcript-repair.ts (L178-L192)
function makeMissingToolResult(params: {
  toolCallId: string;
  toolName?: string;
}) {
  return {
    role: "toolResult",
    toolCallId: params.toolCallId,
    toolName: params.toolName ?? "unknown",
    content: [{
      type: "text",
      text: "[openclaw] missing tool result in session history; " +
            "inserted synthetic error result for transcript repair."
    }],
    isError: true,
    timestamp: Date.now(),
  };
}

repairToolUseResultPairing 完整能力：

这就是我们 v1 中提出的「方案 B：Conversation State Guard」——OpenClaw 早就有了。

Transcript Policy — 按 Provider 控制启用范围

源码位置：src/agents/transcript-policy.ts

// 默认策略
const DEFAULT_TRANSCRIPT_POLICY = {
  repairToolUseResultPairing: true,    // 重排/移动 repair 默认开
  allowSyntheticToolResults: false,    // 但合成缺失 result 默认关
};

// 仅 Google 和 Anthropic 启用合成
...(isGoogle || isAnthropic
  ? { allowSyntheticToolResults: true }
  : {})

Provider 覆盖矩阵：

关键发现：我们使用 amazon-bedrock/global.anthropic.claude-opus-4-6-v1，走 bedrock-converse-stream API，属于 Anthropic 分支，已经启用了合成 tool result repair。

Tool Loop Detection — 循环检测与熔断

源码位置：src/agents/tool-loop-detection.ts

已有内建的工具调用循环检测：

{
  tools: {
    loopDetection: {
      enabled: false,           // 默认关闭
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,     // 重复相同 tool+params
        knownPollNoProgress: true, // 已知轮询无进展
        pingPong: true,          // 交替乒乓模式
      },
    },
  },
}

Agent Timeout 与 LLM Idle Timeout

文档：docs/concepts/agent-loop.md

Agent 总超时：agents.defaults.timeoutSeconds（默认 172800s = 48h）
LLM 空闲超时：agents.defaults.llm.idleTimeoutSeconds（未设时默认 120s）

已有防护的盲区分析

有了源码实证，我们才能准确说出「什么是已有的」和「什么是真正缺的」。

盲区 1：Transcript Repair 的触发时机

Repair 只在构建 LLM 上下文时触发（即下一次 LLM 调用的 sanitizeSessionHistory 阶段），不是实时的。

结论：Repair 解决的是「transcript 中已有的缺失」，不解决「正在等待中的缺失」。这才是真正的盲区。

盲区 2：Agent Timeout 太长

默认 48 小时。工具挂了要等 48 小时才超时——这等于没有超时。

盲区 3：无单个工具级别超时

Agent 有总超时，LLM 有 idle timeout，但单个工具调用没有独立超时。一个 web_fetch 挂了，要等 agent 总超时（48h）才会终止。

盲区 4：Loop Detection 默认关闭

已内建但默认关闭，需要手动开启。

解决方案

基于盲区分析，方案分三档，从零代码到源码 PR。

第一档：配置调优（立即可做，零代码改动）

调低 Agent Timeout

{
  agents: {
    defaults: {
      timeoutSeconds: 1800,  // 48h → 30min
    },
  },
}

效果：session 最多卡 30 分钟（而非 48 小时）后自动终止。
风险：极长的合法任务可能被误杀，可按 agent 单独覆盖。
ROI：★★★★★

显式设置 LLM Idle Timeout

{
  agents: {
    defaults: {
      llm: {
        idleTimeoutSeconds: 90,  // LLM 流式 90s 无 token → 断流
      },
    },
  },
}

效果：防止 LLM API 流式挂起——社区报告的最高频 stuck 模式。
ROI：★★★★★

开启 Tool Loop Detection

{
  tools: {
    loopDetection: {
      enabled: true,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
    },
  },
}

效果：防止工具调用死循环。
ROI：★★★★

第二档：外围 Watchdog（1-2 天，不改核心代码）

用 cron 定期扫描 active session，检测并恢复 stuck：

#!/bin/bash
# session-watchdog.sh — 每 5 分钟运行
STUCK_THRESHOLD=1800  # 30 分钟无活动

openclaw session list --json 2>/dev/null | jq -r '
  .[] | select(.status == "running") |
  select((now - (.lastActivity / 1000)) > '"$STUCK_THRESHOLD"') |
  "\(.id) \(.sessionKey) \(.lastActivity)"
' | while read -r sid skey last; do
  echo "[WATCHDOG $(date)] Stuck: $skey"
  openclaw message send --channel telegram --target 8577482651 \
    --message "⚠️ Stuck session: $skey，超过 ${STUCK_THRESHOLD}s 无活动"
done

效果：提供可见性 + 可选自动恢复。
ROI：★★★★

第三档：源码级改进（需提 PR）

工具级超时（核心缺失项）

在工具执行入口包一层 Promise.race：

async function executeToolWithTimeout(
  toolName: string,
  params: Record<string, unknown>,
  options: { timeoutMs: number }
): Promise<ToolResult> {
  return Promise.race([
    actualToolExecution(toolName, params),
    new Promise<never>((_, reject) =>
      setTimeout(
        () => reject(new ToolTimeoutError(toolName, options.timeoutMs)),
        options.timeoutMs
      )
    ),
  ]).catch((error) => {
    if (error instanceof ToolTimeoutError) {
      // 复用已有的 makeMissingToolResult
      return makeMissingToolResult({
        toolCallId: currentCallId,
        toolName,
      });
    }
    throw error;
  });
}

改动量：~50 行。复用已有的 makeMissingToolResult，新增配置 agents.defaults.tools.timeoutSeconds（默认 300s）。
ROI：★★★★★（根本解决 R1/R2/R4）

扩大合成 Tool Result 的 Provider 覆盖

// src/agents/transcript-policy.ts
const DEFAULT_TRANSCRIPT_POLICY = {
  repairToolUseResultPairing: true,
  allowSyntheticToolResults: true,  // 改为默认开启
};

改动量：1 行。补齐 OpenAI 等 provider 的覆盖。
ROI：★★★

社区方案对比

Tool call stuck 是 AI Agent 领域的普遍问题，几乎所有主流框架都遇到过。

值得借鉴的思路

行动计划

立即执行（今天）

本周

手动恢复 SOP（Stuck Session 排查与恢复标准操作流程）

当 session 真的卡住了，按以下 5 步操作：

Step 1：确认 stuck

# 查看所有 session 状态
openclaw session list --json | jq '.[] | select(.status == "running") | {id, sessionKey, lastActivity, updatedAt}'

# lastActivity 距当前时间 > 10 分钟且 status=running → 疑似 stuck

Step 2：查看日志确认卡在哪

# 实时日志
openclaw logs --follow

# 搜索 tool 相关错误
openclaw logs | grep -i "tool\|timeout\|error\|stuck\|abort" | tail -30

常见卡点判断：

• 日志有 tool start 无 tool end → 工具执行挂起
• 日志有 stream start 无 token 输出 → LLM 流挂起
• 日志无任何输出 → session lane 被占，可能死锁

Step 3：恢复操作

# 方式 1：kill 指定 session（推荐，精准）
openclaw session kill <session-id>

# 方式 2：用户侧发 /kill 命令（如果消息通道还能用）
/kill

# 方式 3：重置 session（丢失当前会话历史）
/reset

# 方式 4：重启 Gateway（最后手段，影响所有 session）
openclaw gateway restart

Step 4：检查残留

# 检查 .lock 文件残留
find ~/.openclaw -name "*.lock" -mmin +30 -ls

# 如有过期 lock，手动清理
find ~/.openclaw -name "*.lock" -mmin +30 -delete

# 确认 session 已恢复
openclaw session list

Step 5：记录事故

记录到运维日志：

• 时间
• 卡死的 session（id + agent）
• 卡死原因（工具挂起 / LLM 挂起 / 其他）
• 恢复方式
• 是否需要后续改进

速查决策树

session 无响应
  │
  ├─ 能发消息？ → 发 /kill
  │
  ├─ 不能发消息？
  │   ├─ 知道 session id → openclaw session kill <id>
  │   └─ 不知道 → openclaw session list 找到后 kill
  │
  ├─ kill 无效？
  │   ├─ 检查 .lock 残留 → 清理
  │   └─ 仍无效 → openclaw gateway restart
  │
  └─ 频繁发生？
      ├─ 检查 agent timeout 配置
      ├─ 开启 loop detection
      └─ 部署 watchdog 脚本

提 PR（推动源码改进）

关键源码文件索引

总结

核心教训：不要在没读源码的情况下提解决方案。OpenClaw 的 transcript repair 机制设计得相当完善，我们真正需要补的只是「正在等待中的工具调用」这个盲区——配置调优解决 80%，工具级超时解决剩下的 20%。

v2 更新说明：基于 OpenClaw GitHub 最新源码（6b126cd）重写，修正了 v1 中「OpenClaw 没有防护」的错误判断，明确了已有机制和真正的盲区，方案聚焦在配置调优 + 补齐工具级超时。

执行摘要

Hermes Agent 是 Nous Research 于 2026 年 2 月 25 日开源的 AI Agent 框架（MIT 协议），7 周内积累了 95,600 GitHub Stars（截至 2026 年 4 月中旬，来源：DEV.to 评测）。其核心差异化能力是闭环学习系统：Agent 在完成复杂任务后自动将工作流提取为可复用的 Skill 文件，后续使用中持续精炼，并通过周期性自省机制（每 10-15 个 turn/task）主动审视是否需要保存记忆或创建新 Skill。

本文对其自动 Skill 创建机制进行源码级深度分析，覆盖触发条件、创建流程、记忆架构、Self-Evolution 系统，并与其他主流 Agent 框架进行对比。

1. 自动 Skill 创建的完整机制

1.1 核心定位：程序性记忆

Hermes Agent 将 Skill 定义为 Agent 的程序性记忆（Procedural Memory）——区别于 MEMORY.md/USER.md 的陈述性记忆（Declarative Memory）。官方文档原文：

“Skills are the agent’s procedural memory — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse.” — Skills System 文档

这一设计哲学的核心洞察是：Agent 应该记住”怎么做”而不仅仅是”知道什么”。成功的工作流被转化为可复用的程序，在下次遇到类似问题时直接加载执行。

1.2 触发条件

根据官方文档和社区评测，Skill 创建在以下场景触发：

关键发现：5 次工具调用阈值。这不是一个硬编码的自动触发器——Hermes 的 Skill 创建主要通过两个机制实现：

1. System Prompt 中的行为指令：系统提示告诉 LLM 在完成复杂任务后应该创建 Skill
2. Periodic Nudge（周期性自省）：每隔 10-15 个 turn，在对话中注入提醒，让 Agent 审视是否需要保存记忆或创建 Skill

重要洞察：这不是传统意义上的”代码触发”，而是通过 prompt engineering 引导 LLM 自主决策是否创建 Skill。Agent 本身并没有一个硬编码的 if tool_calls >= 5: create_skill() 逻辑——而是在 system prompt 中给出指导原则，由 LLM 判断何时该调用 skill_manage(action='create') 工具。

1.3 创建流程（完整链路）

用户任务 → Agent Loop 执行 → 多次工具调用完成任务
                                    ↓
                        LLM 判断是否值得保存为 Skill
                        （基于 system prompt 中的指导原则）
                                    ↓
                        调用 skill_manage(action='create')
                                    ↓
                        skill_manager_tool.py 执行：
                          1. 验证 name（a-z0-9, 小写, ≤64字符）
                          2. 验证 YAML frontmatter（必须包含 name + description）
                          3. 验证内容大小（≤100,000 字符 ≈ 36k tokens）
                          4. 检查名称冲突（跨所有 skill 目录）
                          5. 创建目录 ~/.hermes/skills/[category/]name/
                          6. 原子写入 SKILL.md（tempfile + os.replace）
                          7. 安全扫描（skills_guard 检查注入/外泄模式）
                          8. 扫描失败则回滚（shutil.rmtree）
                                    ↓
                        Skill 可用：自动出现在 system prompt 索引中
                        可作为 /skill-name 斜杠命令使用

1.4 skill_manage 工具的完整 API

基于源码分析（tools/skill_manager_tool.py，795 行，28.5 KB）：

设计哲学要点：

• patch 优先于 edit：官方文档明确说明 patch 更 token 高效，因为只传输变更部分
• 原子写入：所有写操作使用 tempfile + os.replace() 确保不会出现半写状态
• 安全扫描：每次写入后都会运行 skills_guard 安全扫描，检测 prompt injection、数据外泄、破坏性命令等模式。Agent 创建的 Skill 与社区 Hub 安装的 Skill 接受相同的安全审查
• fuzzy matching：patch 操作使用模糊匹配引擎，处理空白标准化和缩进差异

1.5 生成的 Skill 格式与存储

~/.hermes/skills/                    # 单一真实来源（Single Source of Truth）
├── social-media/                    # 类别目录（可选）
│   └── video-to-tweet/              # Agent 创建的 Skill
│       ├── SKILL.md                 # 主指令（必需）
│       ├── references/              # 参考文档
│       ├── templates/               # 输出模板
│       ├── scripts/                 # 辅助脚本
│       └── assets/                  # 补充文件
└── deploy-k8s/                      # 无类别的 Skill
    └── SKILL.md

SKILL.md 格式要求（源码验证）：

---
name: my-skill                       # 必需，小写字母+数字+连字符
description: Brief description       # 必需，≤1024 字符
version: 1.0.0
metadata:
  hermes:
    tags: [category, keywords]
    category: devops
---

# Skill Title

## When to Use
触发条件

## Procedure
1. 步骤一
2. 步骤二

## Pitfalls
- 已知失败模式和修复方法

## Verification
确认成功的方法

1.6 Pattern Extraction 的实现机制

关键发现：Hermes 的 Pattern Extraction 不是一个独立的代码模块，而是完全由 LLM 在运行时完成的。

具体来说：

1. Agent 完成一个复杂任务后，LLM 基于其上下文中的完整执行轨迹（tool calls、结果、错误、修正）
2. System prompt 中的指导原则告诉 LLM：”当你完成了一个复杂任务，应该将方法提取为 Skill”
3. LLM 自行决定提取哪些模式、如何组织 SKILL.md 的内容
4. 通过调用 skill_manage(action='create') 将提取的模式持久化

这意味着 Pattern Extraction 的质量完全取决于底层 LLM 的能力。使用 Claude Opus 4.6 创建的 Skill 质量会显著高于使用较弱模型创建的。

1.7 Progressive Disclosure（渐进式加载）

Skill 使用一个 token 高效的三级加载模式：

这意味着 Agent 只在实际需要时才加载完整 Skill 内容，Level 0 的索引始终注入 system prompt，但完整内容按需加载。

2. Skill 自我改进机制

2.1 Patch vs Edit：精细化更新

Hermes 的 Skill 改进不是”删掉重建”，而是精细化更新：

• patch（首选）：使用 fuzzy find-and-replace，只修改需要变更的部分。Token 成本低，保留 Skill 的整体结构
• edit：完全重写 SKILL.md。用于重大结构重组
• write_file：添加新的参考文件、模板或脚本，丰富 Skill 的辅助材料

自我改进的实际流程（基于 BetterStack 实测文章）：

第1次使用 Skill → 发现边缘情况未覆盖
    → LLM 判断需要更新
    → 调用 skill_manage(action='patch')
    → 添加新的边缘情况处理步骤

第2次使用 → 用户反馈某个步骤不够好
    → LLM 根据反馈调用 patch
    → 修改该步骤的指令

第N次使用 → Skill 越来越精确和完善

2.2 Periodic Nudge 机制

这是 Hermes 学习闭环的关键机制之一：

• 频率：根据不同来源，为每 10 个 turn（BetterStack 实测）或每 15 个 task（LushBinary 开发者指南）
• 机制：在 Agent Loop 中，当 turn 计数达到阈值时，在用户消息中注入一条额外的提示（ephemeral prompt layer），让 Agent 审视：
  1. 最近的对话中是否有值得保存到 MEMORY.md 的信息？
  2. 是否有可以创建为新 Skill 的工作流模式？
  3. 现有 Skill 是否需要更新？

BetterStack 原文描述：

“Every 10 turns, Hermes runs an internal review of the recent conversation and asks whether anything should be saved to persistent memory or automated into a new skill. This is what drives the self-improvement behavior: the agent suggests saving preferences and creating skills without being asked.”

技术实现：这些 nudge 是作为 API-call-time-only layers 注入的，不会修改缓存的 system prompt，从而不影响 prompt caching 效率。它们在特定 turn 被临时添加到 API 请求中，然后丢弃。

2.3 缓存感知设计

Hermes 采用 Frozen Snapshot Pattern（冻结快照模式）：

Session 开始 → 加载 MEMORY.md + USER.md + Skills 索引
            → 冻结为 System Prompt 的一部分
            → 整个 Session 期间不改变

Session 中 → Agent 调用 memory/skill_manage 写入新数据
          → 立即持久化到磁盘
          → 但 System Prompt 中的快照 **不更新**
          → 直到下一个 Session 才生效

为什么这么设计？

• Prompt Caching：主流 API 对稳定的 system prompt 前缀提供缓存优惠。如果每次 memory write 都修改 system prompt，就会破坏缓存，大幅增加 token 成本
• 一致性：避免 session 中途 system prompt 变化导致 LLM 行为不一致
• 性能：冻结快照意味着高频 API 调用可以复用缓存的上下文

这是一个精妙的工程决策——学习不会持续增加你的 token 账单。

3. 三层记忆架构

3.1 架构总览

3.2 层级详解

Layer 1: Session Context（会话上下文）

• 标准的对话历史，使用 OpenAI 兼容的消息格式
• 当超过 50% 上下文窗口时触发压缩
• 压缩策略：保留最新 N 条消息（默认 20 条），中间部分摘要化
• 所有 session 完整保存到 SQLite 数据库

Layer 2: Persistent Store（持久存储）

MEMORY.md（Agent 笔记）：

• 容量：2,200 字符 ≈ 800 tokens
• 内容：环境信息、项目约定、工具技巧、完成的任务记录
• 管理：Agent 通过 memory 工具自动管理（add/replace/remove）

USER.md（用户画像）：

• 容量：1,375 字符 ≈ 500 tokens
• 内容：用户姓名、角色、时区、沟通偏好、技术水平
• 管理：同上

SQLite + FTS5 Session Search：

• 所有 CLI 和消息平台的 session 存储在 ~/.hermes/state.db
• 使用 FTS5 全文搜索索引
• Agent 通过 session_search 工具检索过去的对话
• 支持 Gemini Flash 摘要化，从历史对话中提取相关信息

容量管理的优雅设计：

• 当 MEMORY 超过 80% 时，Agent 会主动合并相关条目
• 如果添加新条目会超限，工具返回错误并展示当前所有条目，让 Agent 决定淘汰哪些
• 自动去重：精确重复的条目被静默拒绝
• 安全扫描：所有记忆条目在接受前会被扫描 injection 和 exfiltration 模式

Layer 3: User Model（用户模型）

Hermes 通过插件系统支持 8 个外部记忆提供商，其中最核心的是 Honcho。

3.3 Honcho Dialectic User Modeling

Honcho（由 Plastic Labs 开发）是一个 AI 原生的跨 session 用户建模系统：

核心概念：辩证推理（Dialectic Reasoning）

Honcho 不是简单地存储用户偏好的 key-value 对，而是通过 peer-to-peer 辩证模型 建立用户理解：

• User Peer：代表人类用户，跨 profile 共享
• AI Peer：代表 AI Agent，每个 Hermes Profile 独立
• Workspace：共享环境，所有 Profile 共用
• Observation：每个 peer 可以独立配置是否观察自己和对方的消息

两层上下文注入：

1. Base Layer（基础层）：session 摘要 + 用户表征 + peer card，按 contextCadence 刷新
2. Dialectic Supplement（辩证补充）：LLM 推理结果，按 dialecticCadence 刷新

三个独立控制旋钮：

漂移调节（Drift-Adjusting）：用户模型不会锁定早期假设，而是根据用户行为变化主动更新。这与简单的偏好存储有本质区别——它模拟的是对用户的”理解”，而非”记录”。

3.4 程序性记忆 vs 陈述性记忆

4. Self-Evolution（DSPy + GEPA）

4.1 hermes-agent-self-evolution 仓库概述

• 仓库: hermes-agent-self-evolution
• 许可: MIT
• 定位: 离线进化优化工具，不是在线运行时组件
• 成本: ~$2-10 每次优化运行（纯 API 调用）
• 无需 GPU

4.2 GEPA：Genetic-Pareto Prompt Evolution

GEPA 是一个来自 ICLR 2026 Oral 论文的算法（MIT 授权），核心思路：

读取当前 Skill/Prompt/Tool → 生成评估数据集
        │
        ▼
   GEPA 优化器 ◄── 执行轨迹
        │         ▲
        ▼         │
   候选变体 ──► 评估
        │
   约束门控（测试、大小限制、benchmark）
        │
        ▼
   最佳变体 ──► PR against hermes-agent

GEPA 的核心创新：它不仅检测”失败了”，还会读取执行轨迹来理解”为什么失败”，然后提出针对性的改进。这类似于遗传算法中的变异，但变异是基于 LLM 的反思推理而非随机。

4.3 评估数据源

# 使用合成数据（从当前 Skill 生成测试场景）
python -m evolution.skills.evolve_skill \
    --skill github-code-review \
    --iterations 10 \
    --eval-source synthetic

# 使用真实 session 历史（来自多种 Agent 工具）
python -m evolution.skills.evolve_skill \
    --skill github-code-review \
    --iterations 10 \
    --eval-source sessiondb

4.4 约束门控机制

每个进化的变体必须通过：

4.5 各阶段进展状态

关键判断：目前只有 Phase 1 完成。这意味着 Self-Evolution 在当前阶段主要是一个Skill 优化工具，而非一个完整的自进化系统。Phase 4 使用的 Darwinian Evolver 来自 Imbue AI，采用 AGPL v3 许可（仅作为外部 CLI 调用）。

5. 源码级分析

5.1 skill_manager_tool.py 核心实现

文件位置: tools/skill_manager_tool.py
规模: 795 行, 28.5 KB
来源: GitHub（2026-04-22 验证）

关键实现细节：

# 常量
MAX_NAME_LENGTH = 64
MAX_DESCRIPTION_LENGTH = 1024
MAX_SKILL_CONTENT_CHARS = 100_000   # ~36k tokens at 2.75 chars/token
MAX_SKILL_FILE_BYTES = 1_048_576    # 1 MiB per supporting file
VALID_NAME_RE = re.compile(r'^[a-z0-9][a-z0-9._-]*$')
ALLOWED_SUBDIRS = {"references", "templates", "scripts", "assets"}

安全设计亮点：

1. Agent 创建的 Skill 与 Hub 安装的 Skill 接受相同安全扫描
2. 三级安全判定：allowed = True（通过）、allowed = False（阻止并报告）、allowed = None（”ask” 判定，对 Agent 创建的 Skill 同样阻止）
3. 原子写入：使用 tempfile + os.replace() 确保写入原子性
4. 路径安全：使用 has_traversal_component 和 validate_within_dir 防止路径遍历
5. 外部目录只读：通过 skills.external_dirs 配置的外部 Skill 目录对 Agent 是只读的

5.2 Agent Loop 中 Skill 创建触发逻辑

基于 run_agent.py（~10,700 行）的源码分析：

# run_agent.py 中检查 skill 工具可用性
has_skills_tools = any(name in self.valid_tool_names 
                       for name in ['skills_list', 'skill_view', 'skill_manage'])

技术事实：skill_manage 是一个注册在 tools/registry.py 中的标准工具。Agent Loop 本身不包含显式的 Skill 创建触发逻辑——触发完全由 LLM 基于 system prompt 中的行为指令自主决策。

这意味着：

• 触发的可靠性取决于 LLM 的指令遵循能力
• 强模型（Claude Opus、GPT-5）会更可靠地遵循 Skill 创建提示
• 弱模型可能忽略这些提示

5.3 关键源码文件映射