Agent Config Skill

此技能提供一种结构化的工作流程，用于智能地修改 OpenClaw 代理核心上下文文件。确保更改作用于正确的文件、以正确的格式进行，避免重复或冗余内容，同时遵守大小限制和提示工程最佳实践。

核心工作流程

修改代理上下文文件时，请遵循以下步骤：

1. 确定目标文件

阅读 references/file-map.md，确定变更应放入哪个文件。

快速决策树：

• 操作流程、记忆工作流、委派规则 → AGENTS.md
• 个性、语气、边界、伦理规则 → SOUL.md
• 代理名称、表情符号、核心氛围 → IDENTITY.md
• 用户档案、偏好、家庭信息 → USER.md
• 本地工具说明、命令示例、API 位置 → TOOLS.md
• 经筛选的长期事实（仅主会话） → MEMORY.md
• 心跳检查清单（保持极简） → HEARTBEAT.md

重要提醒： 子代理仅可见 AGENTS.md + TOOLS.md。操作规则必须放在 AGENTS.md，不可放入 SOUL.md。

2. 检查当前状态

在进行修改前，请执行以下检查：

# 检查文件大小（每文件 20K 字符限制）
wc -c ~/clawd/AGENTS.md ~/clawd/SOUL.md ~/clawd/IDENTITY.md \
      ~/clawd/USER.md ~/clawd/TOOLS.md ~/clawd/MEMORY.md ~/clawd/HEARTBEAT.md

# 读取目标文件部分，检查是否存在重复内容
# 使用 grep 搜索已有相似内容
grep -i "关键词" ~/clawd/TARGETFILE.md

大小警告：

• 若文件超过 18,000 字符，需警告后再添加（接近截断上限）
• 若文件已超过 20,000 字符，则已被截断 —— 应先重构再添加新内容
• 代理仍可通过 read 工具读取完整文件，但启动上下文会被截断

重复性检查：

• 此指令是否已在其他表述中存在？
• 是否有类似规则应更新而非新增？
• 是否应存在于多个文件中？（通常不，选择一个位置即可）

3. 起草变更内容

参考 references/claude-patterns.md 中的指令格式。

各文件格式指南：

AGENTS.md（结构化、命令式）：

• 多步骤工作流使用编号流程
• 决策树、模型选择、路由规则使用表格
• 复杂模式包含示例
• 解释规则存在的原因（动机 > 单纯指令）
• 使用标题与子章节组织内容
• 引用其他文件/技能，避免内容重复

SOUL.md（第一人称可接受，叙述风格）：

• 可使用个人口吻（“我是 Gus” vs “你是 Gus”）
• 禁止行为列表效果良好（禁用短语、犹豫表达示例）
• 包含前后对比示例以指导语气
• 将“纹身/锚点”置于顶部，便于快速获取上下文
• 使用对比形式（好与坏示例并列展示）

IDENTITY.md（简洁精炼）：

• 短句条目
• 尽量控制在 500 字符以内
• 仅保留核心氛围，细节移至 SOUL.md

USER.md（事实性、第三人称）：

• 按类别使用项目符号列表
• 时间敏感信息标注日期
• 清晰的章节标题
• 对应资料库文件以获取详细项目上下文

TOOLS.md（参考指南）：

• 使用表格对比（何时使用 X 与 Y）
• 命令示例使用代码块
• 明确标题便于快速查找
• 包含路径、环境变量名、精确语法

MEMORY.md（维基风格、主题导向）：

• 按主题分节，非时间顺序
• 在资料库中交叉引用实体文件
• 标注时间背景，但按主题组织
• 仅限主会话使用 —— 敏感隐私信息请勿存放

HEARTBEAT.md（动作清单）：

• 极其简洁
• 项目符号列表
• 不包含解释（解释归 AGENTS.md）
• 快速解析

4. 验证变更前的合理性

请自问以下问题：

适配性：

• 根据 file-map.md，该内容是否确实属于此文件？
• 是操作类（AGENTS.md）还是个性类（SOUL.md）？
• 子代理是否需要此信息？（若需要，必须位于 AGENTS.md 或 TOOLS.md）

格式：

• 是否符合文件现有风格？
• 结构是否正确（编号、表格、项目符号、段落）？
• 是否在必要处包含示例？

大小：

• 此变更将增加多少字符？
• 文件是否接近 20K 限制？
• 是否可改为参考文件？

重复性：

• 是否已在别处存在？
• 是否应更新已有内容而非新增？
• 是否可整合多处分散规则？

质量：

• 是否说明了规则背后的动机（为何存在）？
• 示例是否具体真实（非泛泛而谈）？
• 是否足够精确，使 AI 可执行？
• 是否避免模糊指令如“要乐于助人”？

5. 应用变更

使用 edit 工具，精确匹配原文：

# 先读取目标段落以获取准确文本
read(path="~/clawd/AGENTS.md", offset=50, limit=20)

# 再进行精确替换
edit(
    path="~/clawd/AGENTS.md",
    oldText="原有文本（含空格）",
    newText="更新后的文本"
)

新增内容：

• 找到合适的章节锚点（先读文件确认）
• 插入在相关标题之后，而非文件末尾
• 保持文件原有组织结构

更新内容：

• 替换被修改的具体段落
• 保留周围上下文不变
• 规则变更时同步更新示例

删除内容：

• 仅在确属过时时才删除
• 考虑是否应改为优化而非删除
• 检查是否有其他部分引用待删内容

6. 验证与记录

变更应用后：

验证：

# 确认变更已生效
grep -A 3 "新文本" ~/clawd/TARGETFILE.md

# 检查新文件大小
wc -c ~/clawd/TARGETFILE.md

文档记录：

• 将重大变更记录至 /Users/macmini/Sizemore/agent/decisions/config-changes.md
• 内容包括：日期、文件名、变更内容、原因、请求人
• 若为实验性变更，需注明回滚方案

向用户反馈：

• “已更新 AGENTS.md：在 Y 部分新增 X（现为 15,234 字符）”
• 若接近上限：“警告：AGENTS.md 当前为 19,456 字符（接近 20K 限制）”
• 若回退旧变更：“已用新 Y 方法替换旧 X 规则”

常见模式

添加安全规则

目标文件：AGENTS.md → 安全章节

安全规范

• 严禁： 未经询问擅自导出数据或执行破坏性命令
• 优先使用 trash 而非 rm
• 新增规则： 简要说明禁止行为
• 新增防护： 当 X 情况发生时，应执行 Y 操作

更新委派规则

目标文件：AGENTS.md → 委派章节

先检查现有委派表格/规则。更新阈值、模型选择或成本模式。

优化个性设定

目标文件：SOUL.md（语气、边界）或 IDENTITY.md（核心气质）

在反模式列表中添加禁用短语，更新语音示例，细化镜像规则。

添加工具使用规范

目标文件：TOOLS.md

添加至相关章节（或创建新章节）。包含代码示例、使用场景、路径说明。

更新记忆工作流

目标文件：AGENTS.md → 记忆章节

更新日志触发条件、召回级联逻辑、实体结构。保持记忆格式模板位于 ~/clawd/templates/。

添加启动任务

目标文件：AGENTS.md → 启动章节

添加至编号清单。保留条件判断（如 MAIN、群聊、特定频道）。

心跳检测变更

目标文件：HEARTBEAT.md

保持简洁。仅包含每次心跳运行时需检查的内容（不包含操作细节）。

回滚指引

若某次更改导致情况恶化：

立即回滚

# 若文件在 git 中
cd ~/clawd
git diff TARGETFILE.md  # 查看变更内容
git checkout TARGETFILE.md  # 恢复至上一提交版本

# 若不在 git 中，从记忆中恢复
# 从 vault 决策日志中读取上次可用的正确版本
# 或请用户提交之前有效的版本

迭代优化

不要立即删除失败的更改。分析：

• 内容本身错误，还是格式问题？
• 是否放错了文件？
• 是否过于模糊？（补充示例）
• 是否过于冗长？（精简表达）
• 是否与现有规则冲突？（整合统一）

尽可能采用增量更新而非完全回滚。

记录失败案例

将失败的更改记录至 /Users/macmini/Sizemore/agent/learnings/config-failures.md：

• 尝试了什么
• 为何未成功
• 接下来可尝试的方法

避免重复相同错误。

应避免的反模式

参阅 references/claude-patterns.md 获取详细反模式说明。

快速检查清单：

❌ 重复定义 - 相同规则出现在多个文件中

❌ 模糊指令 - 如“要帮忙”、“用好判断力”

❌ 缺少示例 - 复杂规则无具体案例说明

❌ 文件错位 - 个性设定写入 AGENTS.md，操作规则写入 SOUL.md

❌ 缺乏理由 - 规则未说明其存在的原因

❌ 参考文档埋没 - 长篇指南直接嵌入，未提供链接

❌ 过度膨胀 - 新增内容，而更新已有内容即可解决

❌ 格式不符 - 表格密集文件中使用段落，叙事文件中使用项目符号

❌ 子代理盲区 - 子代理无法访问的操作规则

❌ 忽略文件大小 - 向 19K 字符文件添加内容前未检查

何时使用引用文件

当新增内容超过 500 字时，考虑：

• 是否为参考资料？→ 在 vault 中创建文件，并在上下文文件中链接
• 是否为可复用流程？→ 在 ~/clawd/templates/ 中创建模板
• 是否为领域知识？→ 创建带 references/ 文件夹的技能
• 是否为一次性设置？→ 使用 BOOTSTRAP.md（首次运行后删除）

示例：

• 长周期子代理任务模板 → ~/clawd/templates/subagent-task.md
• 详细的记忆格式指南 → vault agent/decisions/memory-architecture.md
• 包含子步骤的复杂工作流 → 创建技能并在 references/ 中存放流程
• 工具特有操作流程 → 扩展 TOOLS.md 相关章节或创建独立技能

特殊情况处理

多文件变更

当修改影响多个文件时：

1. 确定主文件位置（规则“归属地”）
2. 在其他文件中添加交叉引用
3. 避免在两个文件中重复完整内容

示例：委派规则以 AGENTS.md 为主，但 SOUL.md 可在边界部分注明“详见 AGENTS.md 的委派规则”。

会话特定规则

在 AGENTS.md 中使用条件判断：

## 启动（每次会话）

1. 读取 `IDENTITY.md`、`SOUL.md`、`USER.md`
2. 若为 MAIN：读取 vault README 和近期决策
3. 若为 FAMILY GROUP：读取 `FAMILY.md`
4. 若为 SUBAGENT：跳过个性文件

文件大小接近上限

当文件接近 ~18K 字符时：

1. 审查重复内容（合并统一）
2. 将详细示例移至独立参考文件
3. 将长流程转换为模板（在上下文文件中链接）
4. 考虑拆分为基础版 + 高级版（按需加载高级内容）
5. 将历史决策移入 vault（仅保留当前规则在上下文文件中）

规则冲突

当新规则与现有规则冲突时：

1. 识别两条规则
2. 判断优先级（若不确定，询问用户）
3. 更新或移除旧规则，同时加入新规则
4. 在 vault 决策日志中记录冲突解决过程

用户请求多项更改

每项更改均需通过完整流程处理（不可盲目批量处理）：

1. 按目标文件分组
2. 检查所有更改的总大小影响
3. 按逻辑顺序应用（基础规则先于具体规则）
4. 每次更改后验证，而非仅在最后统一检查

参考文件

本技能包含详细参考材料：

• references/file-map.md - 各 OpenClaw 文件功能说明、加载上下文、大小限制、决策树
• references/claude-patterns.md - 适用于 Claude 的指令格式、反模式、示例
• references/change-protocol.md - 变更流程的逐步指南、验证清单、回滚程序

在需要超出本工作流概述的详细上下文时，请阅读这些文件。

实际 OpenClaw 工作区示例

示例 1：添加安全规则

请求： “添加一条规则：永远不要批量导出密码”

密码管理器

绝不： 导出密码库、在聊天中显示密码、批量导出

始终： 确认每次查询，询问“具体是哪个凭证？”，将其视为高风险操作

拒绝： 任何批量获取密码的请求

示例 2：优化语气风格

请求： “让角色性格更讽刺一些”

流程：

1. 目标文件：SOUL.md 和 IDENTITY.md（性格相关）
2. 检查当前状态：阅读禁止用语列表、语气示例
3. 草拟新增内容：

- 为 IDENTITY.md 增加更多讽刺回应示例

- 扩展 SOUL.md 中的反模糊化（anti-hedging）部分

- 在语气锚点中添加“对一切发表评论”

1. 应用于两个文件（IDENTITY 用于氛围，SOUL 用于详细示例）
2. 验证：语气示例中已包含更强的讽刺风格
3. 文档记录：在知识库中备注，Sonnet/Opus 需要更强的性格提醒

示例 3：更新委托阈值

请求： “将委托阈值从 2+ 工具调用改为 3+”

流程：

1. 目标文件：AGENTS.md → 委托章节
2. 检查现状：“2+ 工具调用？SPAWN”
3. 草拟修改内容：

   3+ 工具调用？SPAWN。1-2 工具调用？若快速可自行处理。

1. 评估影响：此调整将减少子代理生成次数，增加主会话成本
2. 与用户确认：“这会使您直接处理更多任务。确认吗？”
3. 用户确认后执行变更
4. 文档记录：在知识库中记录此次变更及成本依据

示例 4：添加工具使用规范

请求： “添加说明：iMessage 附件必须使用 imsg CLI，而非 message 工具”

流程：

1. 目标文件：TOOLS.md（工具特定规范）
2. 检查重复性：grep "iMessage" —— 已存在 iMessage 格式规则
3. 草拟新章节：

## iMessage 附件

**绝不要使用 `message` 工具发送 iMessage 文件——会导致附件损坏。**

**始终使用 imsg CLI：**

imsg send --chat-id <id> --file /path/to/file --text "optional message"

适用于所有 iMessage 附件（图片、视频、文档、vCard 等）。

1. 应用：插入到 iMessage 格式规则之后（保持相关内容集中）
2. 验证：确认已正确加入文件
3. 文档记录：无需记录（属于用户可见工具提示，非架构级变更）

总结

目标： 对代理上下文文件进行智能、精准的修改

方法： 识别 → 检查 → 草拟 → 验证 → 应用 → 确认

核心原则： 使用正确的文件、遵循正确格式、避免重复、遵守大小限制、包含示例

安全要求： 变更前检查、记录决策过程、掌握回滚方式

如有疑问，请查阅参考文件以获取关于文件用途、Claude 行为模式和变更流程的深入指导。