OpenClaw 配置体系和配置技巧

虽然大部分时候大家养虾不用直接手动改这些配置文件，但是你养虾的过程很多时候就是这些配置文件的积累和变化的过程。清楚这些配置和原理，让你更好的养虾！

OpenClaw配置系统架构图

1. 概述

OpenClaw 是一个高度可配置的自主 AI 代理框架，其核心设计理念是“文件即配置”——将代理的人格、记忆、工具使用笔记和用户偏好通过纯 Markdown 文件进行持久化管理。这种设计使得 AI 代理具有跨会话的连续性和可进化的灵魂特性。

配置系统分为两个层级：全局系统配置（位于 ~/.openclaw/openclaw.json）和工作空间引导文件（存放于 ~/.openclaw/workspace）。这种分层架构既保证了系统级参数的统一管理，又赋予了每个代理独立进化的能力。

2. 配置文件清单

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）强调。

配置冲突处理原则：当多个配置文件出现矛盾时，遵循以下优先级（从高到低）：

1. 当前会话中用户的明确指令

2. AGENTS.md 中的红线规则

3. SOUL.md 中的行为边界

4. USER.md 中的偏好设定

5. 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