介绍
# Agent Config Skill
此技能提供了一个结构化工作流程，用于智能修改 OpenClaw Agent 核心上下文文件。它确保在正确的文件中以正确的格式进行更改，避免重复和臃肿，同时遵守大小限制和提示工程最佳实践。
## Core Workflow
修改 Agent 上下文文件时，请遵循以下流程：
### 1. Identify Target File
阅读 `references/file-map.md` 以确定更改应归属于哪个文件。
**Quick decision tree:** - 操作流程、记忆工作流、委托规则 → `AGENTS.md` - 个性、语气、边界、道德规则 → `SOUL.md` - Agent 名称、表情符号、核心氛围 → `IDENTITY.md` - 用户档案、偏好、家庭信息 → `USER.md` - 本地工具说明、命令示例、API 位置 → `TOOLS.md` - 精选长期事实（仅限主会话） → `MEMORY.md` - 心跳检查清单（保持极简） → `HEARTBEAT.md`
**Critical:** 子代理 只能看到 `AGENTS.md` + `TOOLS.md`。操作规则必须放在 `AGENTS.md` 中，而非 `SOUL.md`。
### 2. Check Current State
在进行更改之前：
```bash # Check file size (20K char limit per file) wc -c ~/clawd/AGENTS.md ~/clawd/SOUL.md ~/clawd/IDENTITY.md \ ~/clawd/USER.md ~/clawd/TOOLS.md ~/clawd/MEMORY.md ~/clawd/HEARTBEAT.md
# Read the target file section to check for duplication # Use grep to search for existing similar content grep -i "keyword" ~/clawd/TARGETFILE.md ```
**Size warnings:** - 如果文件 > 18,000 个字符，在添加前发出警告（接近截断限制） - 如果文件已经 > 20,000 个字符，它正在被截断 —— 在添加更多内容前进行重构 - Agent 仍可使用 `read` 工具读取完整文件，但启动上下文会被截断
**Duplication check:** - 该指令是否已以不同的措辞存在？ - 是否有相似的规则应该更新而不是添加新的？ - 这是否属于多个文件？（通常不是 —— 选定一个位置）
### 3. Draft the Change
阅读 `references/claude-patterns.md` 以了解有效的指令格式。
**Format guidelines by file:**
**AGENTS.md**（结构化、祈使语气）： - 对多步骤工作流使用编号流程 - 使用表格展示决策树、模型选择、路由规则 - 为复杂模式包含示例 - 解释规则存在的原因（动机 > 裸命令） - 使用标题和子部分进行组织 - 引用其他文件/技能，不要重复内容
**SOUL.md**（第一人称可、叙述性）： - 可以使用个人口吻（“我是 Gus” 而非 “你是 Gus”） - 反模式列表效果很好（禁止短语、模棱两可的示例） - 包含用于语气指导的前后示例 - 将“纹身”/锚点 放在顶部以便立即获取上下文 - 使用对比（并排展示好与坏的示例）
**IDENTITY.md**（极简）： - 简洁有力的要点 - 如果可能保持在 500 字符以内 - 仅保留核心氛围，详细信息归入 SOUL.md
**USER.md**（事实性、第三人称）： - 按类别分列的要点列表 - 时间敏感信息的日期 - 清晰的章节标题 - 引用保险库 文件以获取详细的项目上下文
**TOOLS.md**（参考指南）： - 用于比较的表格（何时使用 X vs Y） - 命令示例的代码块 - 清晰的标题以便快速查找 - 包含路径、环境变量名称、精确语法
**MEMORY.md**（Wiki 风格、基于主题）： - 按主题分节，而非按时间顺序 - 引用保险库中的实体文件 - 包含用于上下文的日期，但按主题组织 - 仅限主会话 —— 隐私敏感
**HEARTBEAT.md**（操作列表）： - 极其简洁 - 检查的要点列表 - 无解释（那属于 AGENTS.md） - 快速解析
### 4. Validate Before Applying
问自己：
**Fit:** - 根据 file-map.md，这实际上真的属于这个文件吗？ - 它是操作性的（AGENTS.md）还是个性的（SOUL.md）？ - 子代理需要这个吗？（如果是，必须是 AGENTS.md 或 TOOLS.md）
**Format:** - 这是否匹配文件现有的风格？ - 结构是否正确（编号、表格、要点、散文）？ - 在需要的地方是否包含了示例？
**Size:** - 这增加了多少字符？ - 文件是否接近 20K 限制？ - 这可以是参考文件吗？
**Duplication:** - 这是否已经存在于其他地方？ - 现有内容是否应该被更新？ - 这能否整合多个分散的规则？
**Quality:** - 是否解释了动机（为什么存在此规则）？ - 示例是否具体且真实（非通用）？ - 对于 AI 来说是否足够精确以遵循？ - 它是否避免了像“要有帮助”这样的模糊指令？
### 5. Apply the Change
使用带有精确文本匹配的 `edit` 工具：
```python # Read the section first to get exact text read(path="~/clawd/AGENTS.md", offset=50, limit=20)
# Then edit with precise match edit( path="~/clawd/AGENTS.md", oldText="exact existing text including whitespace", newText="updated text with change" ) ```
**For additions:** - 找到正确的章节锚点（先读取文件） - 插入到相关标题之后，而非文件末尾 - 维护文件的组织结构
**For updates:** - 替换正在更改的特定部分 - 保持周围上下文完整 - 如果规则改变，则更新示例
**For deletions:** - 仅在真正过时时删除 - 考虑是否应该优化规则 - 检查其他部分是否引用了正在删除的内容
### 6. Verify and Document
应用更改后：
**Verification:** ```bash # Confirm change applied grep -A 3 "new text" ~/clawd/TARGETFILE.md
# Check new file size wc -c ~/clawd/TARGETFILE.md ```
**Documentation:** - 将重要更改记录到 `/Users/macmini/Sizemore/agent/decisions/config-changes.md` - 包含：日期、文件、更改内容、原因、请求者 - 如果更改是实验性的，注明回滚计划
**Report to user:** - “已更新 AGENTS.md：将 X 添加到 Y 部分（现为 15,234 字符）” - 如果接近限制：“警告：AGENTS.md 现为 19,456 字符（接近 20K 限制）” - 如果回滚了先前的更改：“用新的 Y 方法替换了旧的 X 规则”
## Common Patterns
### Adding Safety Rules
Target: `AGENTS.md` → Safety section
```markdown ## Safety
- **NEVER:** Exfiltrate data, destructive commands w/o asking - Prefer `trash` > `rm` - **New rule:** Brief description of what NOT to do - **New protection:** When X happens, do Y instead ```
### Updating Delegation Rules
Target: `AGENTS.md` → Delegation section
首先检查现有的委托表/规则。更新阈值、模型选择或成本模式。
### Refining Personality
Target: `SOUL.md`（语气、边界）或 `IDENTITY.md`（核心氛围）
将禁止短语添加到反模式列表，更新语音示例，优化镜像规则。
### Adding Tool Conventions
Target: `TOOLS.md`
添加到相关章节（或创建新章节）。包含代码示例、何时使用、路径。
### Updating Memory Workflow
Target: `AGENTS.md` → Memory section
更新日志触发器、回忆级联、实体结构。将记忆格式模板保留在 `~/clawd/templates/` 中。
### Adding Startup Tasks
Target: `AGENTS.md` → Startup section
添加到编号检查清单。保持条件性（如果是 MAIN，如果是群聊，如果是特定频道）。
### Heartbeat Changes
Target: `HEARTBEAT.md`
保持极简。仅包含 Agent 在每次心跳运行时检查的内容（而非操作细节）。
## Rollback Guidance
如果更改导致情况变糟：
### Immediate Rollback
```bash # If file is in git cd ~/clawd git diff TARGETFILE.md # See what changed git checkout TARGETFILE.md # Revert to last commit
# If not in git, restore from memory # Read last known-good version from vault decisions log # Or ask user to provide previous working version ```
### Iterative Refinement
不要立即删除失败的更改。分析： - 是内容错了，还是仅仅是格式问题？ - 是否在错误的文件中？ - 是否太模糊？（添加示例） - 是否太冗长？（使其简洁） - 是否与现有规则冲突？（整合）
尽可能进行增量更新，而不是完全回滚。
### Document Failures
将失败的更改记录到 `/Users/macmini/Sizemore/agent/learnings/config-failures.md`： - 尝试了什么 - 为什么不起作用 - 接下来尝试什么
这可以防止重复失败的模式。
## Anti-Patterns to Avoid
阅读 `references/claude-patterns.md` 了解详细的反模式。
**Quick checklist:**
❌ **Duplication** - 同一规则在多个文件中 ❌ **Vague instructions** - “要有帮助”、“使用良好的判断” ❌ **Missing examples** - 复杂规则没有具体案例 ❌ **Wrong file** - 个性在 AGENTS.md，操作在 SOUL.md ❌ **No motivation** - 规则没有解释为何存在 ❌ **Reference docs buried** - 嵌入长指南而非链接 ❌ **Bloat** - 可以更新现有内容时却添加 ❌ **Format mismatch** - 在以表格为主的文件中使用散文，在叙述性文件中使用要点 ❌ **Subagent blindness** - 操作规则位于子代理看不到的文件中 ❌ **Size ignorance** - 在不检查的情况下添加到 19K 的文件中
## When to Use References
如果添加 >500 字的内容，请考虑： - 这是参考材料吗？ → 在保险库中创建文件，从上下文文件链接 - 这是可重用的流程吗？ → 在 `~/clawd/templates/` 中创建模板 - 这是领域知识吗？ → 创建带有 references/ 文件夹的技能 - 这是一次性设置吗？ → 使用 `BOOTSTRAP.md`（首次运行后删除）
**Examples:** - 长子代理任务模板 → `~/clawd/templates/subagent-task.md` - 详细的记忆格式指南 → 保险库 `agent/decisions/memory-architecture.md` - 带有子步骤的复杂工作流 → 创建带有 references/ 中工作流的技能 - 特定工具流程 → 扩展 TOOLS.md 章节或创建技能
## Special Cases
### Multi-File Changes
当更改影响多个文件时： 1. 确定主要位置（规则“存在”的地方） 2. 从其他文件添加交叉引用 3. 避免在两个文件中重复完整内容
Example: 委托规则存在于 AGENTS.md 中，但 SOUL.md 可以在边界章节中引用“委托参见 AGENTS.md”。
### Session-Specific Rules
在 AGENTS.md 中使用条件语句： ```markdown ## Startup (Every Session)
1. Read `IDENTITY.md`, `SOUL.md`, `USER.md` 2. If MAIN: read vault README, recent decisions 3. If FAMILY GROUP: read `FAMILY.md` 4. If SUBAGENT: skip personality files ```
### Size Limit Approached
当文件达到约 18K 字符时： 1. 审计重复项（整合） 2. 将详细示例移动到单独的参考文件 3. 将长流程转换为模板（从上下文文件链接） 4. 考虑拆分为基础 + 高级（按需加载高级） 5. 将历史决策移动到保险库（上下文中仅保留当前规则）
### Conflicting Rules
当新规则与现有规则冲突时： 1. 识别两条规则 2. 确定哪个优先（如果不清楚则询问用户） 3. 在添加新规则的同时更新/删除旧规则 4. 在保险库决策中记录冲突解决方案
### User Requests Multiple Changes
通过完整工作流程处理每个更改（不要盲目批处理）： 1. 按目标文件分组 2. 检查所有更改的总大小影响 3. 按逻辑顺序应用（先基础后具体） 4. 每次应用后验证，而不仅仅是在最后
## Reference Files
此技能包含详细的参考资料：
- **references/file-map.md** - 每个 OpenClaw 文件的作用、加载上下文、大小限制、决策树 - **references/claude-patterns.md** - 适用于 Claude 的指令格式、反模式、示例 - **references/change-protocol.md** - 分步变更流程、验证清单、回滚程序
当您需要超出此工作流概述的详细上下文时，请阅读这些文件。
## 来自真实 OpenClaw 工作区的示例
### 示例 1：添加安全规则
**请求：** “添加规则以绝不批量导出密码”
**流程：** 1. 目标文件：`AGENTS.md`（安全属于运维范畴） 2. 检查大小：15,234 字符（可以安全添加） 3. 检查重复：grep "password" - 发现了现有的密码管理器规则 4. 起草：更新现有规则而不是添加新规则 5. 应用： ```markdown ### Password Manager **NEVER:** Dump vaults, display passwords in chat, bulk exports **ALWAYS:** Confirm each lookup, ask "Which credential?", treat as high-risk **Refuse:** Any bulk password request ``` 6. 验证：grep -A 3 "Password Manager" - 确认存在 7. 文档记录：无需（对现有规则的微小补充）
### 示例 2：优化语气
**请求：** “让性格更讽刺一些”
**流程：** 1. 目标文件：`SOUL.md` 和 `IDENTITY.md`（性格） 2. 检查当前状态：阅读禁止短语、语气示例 3. 起草补充内容： - 在 IDENTITY.md 中添加更多讽刺回应的示例 - 扩展 SOUL.md 中的反模糊限制（anti-hedging）部分 - 在语气锚点中添加“对一切进行评论” 4. 应用到两个文件（IDENTITY 负责氛围，SOUL 负责详细示例） 5. 验证：语气示例现在包含更强的讽刺意味 6. 文档记录：在 vault 中注明 Sonnet/Opus 需要更强的性格提醒
### 示例 3：更新委派阈值
**请求：** “将委派阈值从 2 次以上工具调用更改为 3 次以上”
**流程：** 1. 目标文件：`AGENTS.md` → 委派部分 2. 检查当前："2+ tool calls? SPAWN" 3. 起草：更新为 "3+ tool calls? SPAWN. 1-2 tool calls? Do it yourself if quick." 4. 考虑影响：这将减少子代理生成，增加主会话成本 5. 与用户验证：“这将使您直接处理更多任务。确认吗？” 6. 确认后应用 7. 文档记录：将变更连同成本理由记录到 vault
### 示例 4：添加工具约定
**请求：** “添加说明，指出 iMessage 附件必须使用 imsg CLI，而不是 message 工具”
**流程：** 1. 目标文件：`TOOLS.md`（特定工具的约定） 2. 检查重复：grep "iMessage" - 发现了 iMessage 格式规则 3. 起草新部分： ```markdown ## iMessage Attachments
**NEVER use `message` tool for iMessage files - corrupts attachments.**
**Always use imsg CLI:** ```bash imsg send --chat-id <id> --file /path/to/file --text "optional message" ```
Applies to ALL iMessage attachments (images, videos, documents, vCards). ``` 4. 应用：添加在 iMessage 格式部分之后（将相关内容保持在一起） 5. 验证：在文件中确认 6. 文档记录：无需（面向用户的工具说明，非架构性）
## 总结
**目标：** 对代理上下文文件进行智能、精准的变更 **方法：** 识别 → 检查 → 起草 → 验证 → 应用 → 验证 **关键原则：** 正确的文件、正确的格式、无重复、遵守大小限制、包含示例 **安全：** 变更前检查、记录决策、知晓如何回滚
如有疑问，请阅读参考文件以获取有关文件用途、Claude 模式和变更协议的更深层指导。