夜雨聆风1. 概述
OpenClaw 是一个高度可配置的自主 AI 代理框架，其核心设计理念是“文件即配置”——将代理的人格、记忆、工具使用笔记和用户偏好通过纯 Markdown 文件进行持久化管理。这种设计使得 AI 代理具有跨会话的连续性和可进化的灵魂特性。
配置系统分为两个层级：全局系统配置（位于 ~/.openclaw/openclaw.json）和工作空间引导文件（存放于 ~/.openclaw/workspace）。这种分层架构既保证了系统级参数的统一管理，又赋予了每个代理独立进化的能力。后面 workspace 的配置是针对单个 agent 的。
2. 配置文件清单
OpenClaw配置系统架构图
3. 核心配置文件详解
3.1 SOUL.md：代理的灵魂
SOUL.md 是代理行为准则的核心载体。官方模板强调代理不应是复读机，而应具有独立观点和资源意识。
3.2 AGENTS.md：做事逻辑
该文件规定代理在每个会话开始时的标准动作和红线，这个文件会随着养虾越来越丰富，越来越大。
3.3 USER.md与TOOLS.md
USER.md 记录用户的称呼偏好、时区及项目背景，帮助代理提供个性化服务。TOOLS.md 用于存放特定环境的硬件配置，弥补通用技能与本地环境之间的差异。
4. 配置协作流程
OpenClaw 的配置文件在代理生命周期中形成三阶段协作流：
5. 最佳实践
基于官方文档和社区经验总结的四项核心实践：
-----------------------------------------------
如果暂时不涉及到具体文件的修改，下面的使用技巧细节可以跳过，了解上面的就好了。
6. 配置文件配置与使用技巧
本节提供各核心配置文件的实战配置示例、常见场景配置方法及注意事项。
6.1 SOUL.md 配置细节
SOUL.md 是塑造代理人格的核心文件，其配置质量直接决定代理的行为表现。以下是一个完整的配置模板示例：
人格塑造技巧：避免复读机行为的关键在于明确要求代理”拥有独立观点”。可在 Core Truth 部分添加类似 I form my own conclusions based on evidence rather than simply echoing user statements 的声明。同时，鼓励代理在提问前先尝试自行推理，减少不必要的确认请求。
不同场景的人格配置对比：
6.2 AGENTS.md 配置实战
AGENTS.md 定义代理的运行时行为，是确保代理稳定执行的关键文件。这个配置会随着你的使用会内容越来越多，也是你的龙虾的某个agent的重要辅助配置文件，中文用户建议改成中文。以下是推荐的启动流程配置：
红线规则配置要点：红线规则的核心是防止不可逆操作。建议将所有涉及外部系统（邮件、社交媒体、支付）的动作都列入需要许可的清单。配置时使用大写的 NEVER 和 ALWAYS 来强调约束的绝对性。
记忆检索强制指令：上下文压缩（Compaction）会导致聊天记录丢失，因此必须在 AGENTS.md 中明确写入记忆检索指令。推荐配置为 Before taking any significant action, I MUST run memory_search with relevant keywords，确保代理在行动前主动回顾历史。
6.3 USER.md 配置实战
USER.md 用于存储使用龙虾的用户的画像，帮助代理提供个性化服务。以下是完整的配置示例：
多用户场景处理：当多个用户共享同一代理时，可以采用分区配置的方式。在 USER.md 中使用二级标题区分不同用户（如User: Alex 和 User: Jordan），并在 AGENTS.md 中添加逻辑判断当前对话者身份。
项目上下文注入：对于长期项目，建议在 USER.md 中维护一个 Current Projects 部分，包含项目名称、技术栈、关键里程碑和截止日期。这使代理能够在相关对话中自动关联项目背景，减少重复解释。
6.4 TOOLS.md 配置实战
TOOLS.md 弥补了通用技能与本地环境之间的差异。以下是典型的环境配置示例：
本地工具别名映射：建议将所有常用的 SSH 主机、数据库连接和 API 端点都配置为易记的别名。代理在执行命令时会参考这些别名，避免每次都需要用户提供完整的连接信息。
环境特定参数记录格式：使用 Markdown 表格来组织硬件配置，确保信息结构化且易于检索。对于每个设备，至少记录名称、位置、关键参数和用途四个字段。
6.5 MEMORY.md 配置实战
MEMORY.md 存放经过蒸馏的长期记忆，是代理知识积累的核心载体。推荐的结构化存储格式如下：
记忆蒸馏技巧：并非所有信息都值得长期保存。以下是蒸馏决策的参考标准：
定期维护建议：建议每周对 MEMORY.md 进行一次审查，删除过时信息，合并重复条目。可在 AGENTS.md 中配置周期性提醒，例如 Every Sunday, remind user to review and clean MEMORY.md。
6.6 openclaw.json 系统配置
openclaw.json 是系统级配置文件，控制模型选择、内存搜索和全局行为。以下是推荐配置示例：
内存搜索参数调优：混合搜索（Hybrid Search）结合了 BM25 文本匹配和向量语义搜索。默认权重 0.3:0.7 适合大多数场景；若用户查询偏向精确关键词匹配，可将 BM25 权重提高至 0.5；若偏向语义理解，可降至 0.2。MMR（Maximal Marginal Relevance）用于平衡相关性与多样性，diversityBias 值越高，返回结果越多样化。
API 密钥安全管理：严禁在配置文件中硬编码 API 密钥。推荐使用环境变量引用（如 ${OPENAI_API_KEY}）或系统密钥管理服务。同时，确保 openclaw.json 的文件权限设置为 600，仅允许所有者读写。
6.7 配置调试与常见问题
在实际使用中，配置问题是最常见的故障来源。以下是排查方法和解决方案：
配置不生效排查清单：
上下文压缩导致规则丢失的解决方案：OpenClaw 会对长对话进行上下文压缩（Compaction），这可能导致聊天中临时设定的规则丢失。解决方法是将所有需要持久化的规则写入 AGENTS.md 或 SOUL.md，而非仅在聊天中口头约定。关键规则应使用大写关键词（如 MUST、NEVER、ALWAYS）强调。
配置冲突处理原则：当多个配置文件出现矛盾时，遵循以下优先级（从高到低）：
当前会话中用户的明确指令 AGENTS.md 中的红线规则 SOUL.md 中的行为边界 USER.md 中的偏好设定 openclaw.json 中的默认值
若发现配置冲突，建议在 AGENTS.md 中明确声明优先级规则，例如 When conflicts arise, AGENTS.md red lines take precedence over USER.md preferences。
参考
[1] GitHub, 2026-02-17. OpenClaw配置文件详解. https://raw.githubusercontent.com/openclaw/openclaw/main/docs
