《OpenClaw AI 高阶实战》第6章授课

OpenClawAI高阶实战第6章：AGENTS.md工作规范——定义AI的“打工守则”授课对象：有基础的开发人员课时：2小时课程大纲核心价值与背景为什么需要“打工守则”：AGENTS.md的核心价值启动流程定义Session启动时自动加载哪些文件规范记忆写入如何定义记忆的存储规则设定安全边界区分可自由执行与需用户确认的操作配置项详解AGENTS.md配置项详解与最佳实践实战案例演练为“个人助理”AI定制工作规范问题排查与调试常见问题排查与配置调试技巧总结与课后任务本章知识点总结与实践作业从“散兵游勇”到“正规军”：AGENTS.md的核心价值问题现状：无守则的AI每次启动都是“全新”的，缺乏身份认知。生成的记忆杂乱无章，缺乏统一管理。存在执行危险操作（如误删文件）的风险。角色：AI的“员工手册”工作流程：明确启动流程，规范每日工作开始方式。工作规范：定义记忆写入标准，确保成果有序存储。行为边界：划定安全红线，明确请示汇报机制。价值：构建可控AI系统将AI从不可预测的“黑盒”转变为可管理的“智能助理”。确保行为可预测、安全可靠，是实现复杂自动化系统的关键基石。定义启动流程：Session启动时自动加载哪些文件核心配置机制核心问题：AI在启动新Session时，需自动加载记忆文件以初始化状态，避免重复介绍。配置项：session_startup_scripts身份与人格文件SOUL.md,USER.md,IDENTITY.md记忆与项目文件MEMORY.md,projects/*.md,lessons.md配置示例(AGENTS.md)session_startup_scripts:-./SOUL.md#加载人格设定-./USER.md#加载用户信息-./MEMORY.md#加载全局记忆-./projects/work.md#加载重点项目效果：AI启动时自动加载，拥有一致的“初始状态”和背景信息。规范记忆写入：如何定义记忆的存储规则核心配置与规则定义核心问题：如何组织AI生成的对话日志、经验总结等新记忆，确保数据整洁可管理？日志存储路径(log_path)定义日志文件的保存位置，支持按日期动态分割，避免单一文件过大。经验总结触发(auto_lesson_summary)设置关键词（如“总结”、“经验”），触发自动总结并写入lessons.md。项目关联规则建立记忆与项目的自动关联机制，确保信息归属清晰。配置示例(AGENTS.md)#AGENTS.mdmemory_writing_rules:log_path:"./logs/daily_log_{{date}}.md"auto_lesson_summary:truelesson_trigger_keywords:["总结","经验"]预期效果所有新生成的记忆将遵循统一规范存储，大幅提升后续检索、分析和管理的效率。设定安全边界：区分可自由执行与需用户确认的操作核心原则：最小权限原则AI只能执行完成其工作所必需的操作，严禁赋予超出工作范围的权限。权限控制模式对比白名单模式(推荐)明确列出允许执行的操作，默认禁止所有未列出操作。安全性最高。黑名单模式仅列出禁止的高风险操作，可能遗漏未知风险，安全性较低。白名单配置示例(YAML)#AGENTS.md-权限配置permissions:mode:"whitelist"allowed_actions:-"read_file"require_confirmation_for:-"delete_file"-"execute_system_command"运行效果当AI试图执行高风险操作（如删除文件）时，系统会自动暂停并向用户发送确认请求，等待人工授权。AGENTS.md配置项详解与最佳实践（一）核心配置项解析与实践指南，帮助您构建高效、稳定的Agent系统。配置项名称核心作用配置示例最佳实践建议session_startup_scripts定义Session启动时自动加载的文件列表["./SOUL.md","./MEMORY.md"]只加载必要的核心文件，避免信息过载。可按场景配置不同脚本。memory_writing_rules.log_path定义日志文件的存储路径和命名规则"./logs/daily_{{date}}.log"使用日期模板按天分割日志，便于查找和归档。memory_writing_rules.auto_lesson_summary是否开启自动经验总结功能true/false建议开启，配合触发条件，避免总结泛滥。memory_writing_rules.lesson_trigger_keywords触发自动经验总结的关键词["总结","经验","教训"]设置最能代表“需要总结”的关键词，提高准确性。AGENTS.md配置项详解与最佳实践（二）重点关注与安全权限相关的配置项，这是保障系统安全的重中之重。配置项作用配置示例最佳实践建议permissions.mode权限控制模式"whitelist"/"blacklist"强烈推荐使用白名单模式，默认禁止所有操作，安全性最高。permissions.allowed_actions白名单允许操作列表["read_file","write_log"]严格遵循“最小权限原则”，只添加完成任务必需的操作。permissions.require_confirmation_for需用户确认的操作列表["delete_file","send_email"]将所有高风险操作加入此列表，确保用户拥有最终控制权。permissions.restricted_actions黑名单禁止操作列表["format_disk"]不推荐使用黑名单模式，无法穷举所有危险操作，存在隐患。AGENTS.md配置前后效果对比对比维度配置前（无AGENTS.md）配置后（有AGENTS.md）启动状态每次启动都是“白板”状态，无记忆、无人格，需用户重新介绍。自动加载指定人格、用户信息和记忆文件，拥有一致且丰富的初始状态。记忆存储记忆存储位置任意，格式混乱，难以查找和管理。所有记忆按统一规则存储，结构清晰，可通过标签和路径快速检索。行为安全性行为不可控，可能执行高风险操作，系统安全无法保障。严格遵循权限规则，高风险操作需用户确认，安全性得到极大提升。整体可控性AI像不受约束的“黑盒”，行为不可预测，难以融入复杂工作流。AI像遵守规则的“员工”，行为可预测、可管理，是构建自动化系统的可靠组件。实战案例：为“个人助理”AI定制工作规范案例背景与需求启动时加载人格与用户信息安全读写文件，记录待办与笔记具备经验总结能力，限制删除/发邮件权限核心配置目标制定一份完整的AGENTS.md配置文件，实现上述需求，打造一个安全、可靠、智能的个人助理系统。配置步骤分解定义启动流程与记忆写入规则设定安全权限边界，限制高危操作整合配置项并进行完整验证案例步骤：定义启动流程与记忆写入规则第一步：配置启动流程启动时加载AI的人格（SOUL.md）、用户信息（USER.md）和全局记忆索引（MEMORY.md）。#AGENTS.mdsession_startup_scripts:-./SOUL.md#加载AI的“个人助理”人格-./USER.md#加载用户的个人信息和偏好-./MEMORY.md#加载全局记忆索引第二步：配置记忆写入规则日志按天存储在logs目录下，当用户提到“总结”或“经验”时自动触发总结。memory_writing_rules:log_path:"./logs/assistant_log_{{date}}.md"auto_lesson_summary:truelesson_trigger_keywords:["总结","经验","教训"]案例步骤：设定安全权限边界需求分析：权限分类允许的操作（自由执行）读取文件（查看笔记）、写入文件（创建/更新待办）写入日志、总结经验需要确认的操作（高风险）删除文件（不可逆操作）发送邮件、执行系统命令（外部影响）配置实现：白名单模式permissions:mode:"whitelist"#核心模式allowed_actions:-"read_file","write_file","write_log"require_confirmation_for:-"delete_file","send_email","execute_system_command"配置解读通过白名单模式，AI可以安全地管理文件和笔记。任何可能造成破坏或有外部影响的操作都被严格限制，必须经过用户明确授权，确保系统安全性。案例步骤：完整的“个人助理”AGENTS.md配置文件将前两步的配置整合起来，我们就得到了一份完整的、可直接使用的AGENTS.md配置文件。AGENTS.md-个人助理AI的工作守则#1.启动流程配置session_startup_scripts:-./SOUL.md#加载人格-./USER.md#加载用户偏好-./MEMORY.md#加载记忆索引#2.记忆写入规则memory_writing_rules:log_path:"./logs/assistant_log_{{date}}.md"auto_lesson_summary:true#3.安全权限边界(白名单模式)permissions:mode:"whitelist"allowed_actions:["read_file","write_file","summarize_lesson"]案例步骤：验证“个人助理”配置效果测试场景1：执行允许的操作用户指令：在notes/目录下创建shopping_list.md文件，写入“牛奶、面包、鸡蛋”。AI行为：检查权限，确认write_file在白名单中，直接执行操作。结果：文件创建成功，操作高效完成，无需用户确认。测试场景2：执行需要确认的操作用户指令：删除notes/old_notes.md文件。AI行为：检测到delete_file在确认列表中，暂停操作并请求用户确认。结果：仅在用户明确回复“确认删除”后执行，有效防止误操作。结论：配置完全生效，AI的行为既高效又安全，完全符合我们的设计预期。常见问题排查：AGENTS.md配置不生效问题现象修改了AGENTS.md的配置文件，但AI的行为没有任何变化，配置未按预期生效。排查思路（按优先级）1.检查文件格式(最常见)AGENTS.md是YAML格式，对缩进和符号敏感。建议使用验证语法。2.检查文件路径和名称确保文件位于工作目录根目录，且文件名大小写正确（如AGENTS.md）。3.检查配置项名称核对OpenClaw官方文档，确保使用的配置项名称未过时或不存在。4.重启Session或服务部分配置生效需要重启对话Session或OpenClaw服务。常见问题排查：权限配置过严或过松现象1：权限过严，影响效率表现：AI频繁要求确认，无法执行必要操作，流程繁琐。

排查与解决：检查`allowed_actions`列表，确认是否遗漏必要权限。将安全的高频操作添加到允许列表中。现象2：权限过松，存在隐患表现：AI无需确认即可执行高风险操作（如删除文件）。

排查与解决：检查`require_confirmation_for`列表是否包含高风险操作。审查白名单，确保未误将危险操作加入允许列表。最佳实践：平衡安全与便捷遵循“最小权限原则”，定期审查权限配置，根据AI实际工作内容动态调整，确保在安全性和使用便捷性之间找到最佳平衡点。配置调试技巧：开启详细日志核心技巧：调整日志级别将日志级别设置为DEBUG或INFO，系统会输出配置加载、权限检查等详细运行信息。关键分析阶段启动阶段：文件加载确认查找"LoadingAGENTS.md"或"Loadingstartupscript"，确认配置文件是否被正确加载。权限阶段：规则应用检查查找"Checkingpermission"或"Actionallowed"，确认权限策略是否生效。记忆阶段：写入规则验证查找"Writinglogto"或"Auto-generatinglesson"，确认记忆系统正常工作。典型日志片段示例[DEBUG]Loadingconfigurationfrom:./AGENTS.md[INFO]Sessionstartup:Loadingscript:./SOUL.md[INFO]Sessionstartup:Loadingscript:./USER.md[DEBUG]Usercommandreceived:'deletefile'[DEBUG]Checkingpermissionforaction:'delete_file'[WARNING]Action'delete_file'requiresuserconfirmation.结论：通过分析日志，我们可以清晰地看到系统内部的执行流程，快速定位配置问题所在。本章总结：AGENTS.md核心配置与实践核心认知：AI员工手册AGENTS.md是定义AI行为规范的基石，它决定了AI