23.1 OpenClaw 核心配置文件

面向经管学生、研究者与从业者的 AI 智能体设计教材

作者

李学恒、林建浩、严翊歆

发布于

2026-05-11

OpenClaw 管家的所有配置都存放在一个工作区（workspace）目录中，默认路径为 ~/.openclaw/workspace。工作区包含多种文件和子目录，本节聚焦其中最核心的 7 个配置文件。它们共同定义了管家是谁、如何工作、为谁服务。

配置文件总览

文件	定位	每轮注入
`IDENTITY.md`	身份记录：名字、类型、emoji	是
`SOUL.md`	人格风格：语气、观点、幽默感	是
`USER.md`	用户信息：称呼、时区、关注领域	是
`AGENTS.md`	操作规则：行为边界、安全红线	是
`TOOLS.md`	本地工具备忘：设备名称、偏好配置	是
`MEMORY.md`	长期记忆：持久性事实与决策	仅主会话
`HEARTBEAT.md`	心跳任务清单：周期性自动检查	仅心跳启用时

自动注入

管家每次启动会话时，会将这些配置文件的内容注入对话上下文。MEMORY.md 仅在一对一会话中注入，群组对话中不加载，避免个人信息泄露。HEARTBEAT.md 只在心跳功能开启时才注入。

下面按职能分组介绍每个文件。

身份与人格

IDENTITY.md

IDENTITY.md 记录管家的基本身份信息。内容简短，通常在首次对话中生成。

# IDENTITY.md - Who Am I?

Name: 小橙
Creature: AI 管家
Vibe: 温和、专注、偶尔冷幽默
Emoji: 🍊
Avatar: avatar.png

这个文件回答一个问题：管家叫什么、是什么。名字和 emoji 会出现在对话界面中。

SOUL.md

SOUL.md 定义管家的人格风格。如果说 IDENTITY.md 是”我是谁”，SOUL.md 就是”我怎么说话、怎么思考”。

# SOUL.md - Who You Are

## Core Truths
- 简洁优先，不说废话
- 有观点，敢表达，但不固执
- 对用户坦诚，不迎合

## Boundaries
- 不编造数据
- 不假装知道不知道的事

## Vibe
- 像一个靠谱的同事：专业但不冷漠
- 回答控制在必要长度，不铺垫不总结

## Continuity
- 记住之前的讨论，不重复问已回答的问题

SOUL.md 的写作原则是短而锐利。官方建议避免写成”企业手册风格”。每一条都应该能直接影响管家的语言行为。

USER.md

USER.md 记录用户信息，让管家了解它在帮助谁。

# USER.md - About Your Human

Name: 张明
What to call them: 张老师
Timezone: Asia/Shanghai

## Notes
- 经济金融研究员，关注宏观经济与资产配置
- 偏好结构化产出（表格、要点、带数据支撑的结论）

## Context
- 当前在做一个关于中国制造业 PMI 的季度分析项目
- 经常需要整理多个数据源的对比表格

这个文件随时间积累。管家越了解用户，越能提供贴合需求的帮助。

操作规则

AGENTS.md

AGENTS.md 是管家的操作规则文件，规定行为边界和安全约束。

# AGENTS.md - Your Workspace

## Session Startup
- 会话开始时读取 MEMORY.md，了解上下文
- 检查是否有未完成的任务

## Memory
- 重要决策和事实写入 MEMORY.md
- 不记录临时性、一次性的对话内容

## Red Lines
- 不在未经确认的情况下执行外部 API 调用
- 不删除用户文件
- 不发送消息给第三方

## External vs Internal
- 涉及外部操作（发邮件、调用 API）时先询问
- 内部操作（读文件、写笔记）可直接执行

AGENTS.md 与 SOUL.md 的区分

SOUL.md 管”风格”：语气、观点、简洁度。AGENTS.md 管”规则”：什么能做、什么不能做、什么需要先问。一个是性格，一个是纪律。

工具备忘

TOOLS.md

TOOLS.md 记录用户本地环境的具体信息，供管家在调用工具时参考。

# TOOLS.md - Local Notes

## SSH
- dev-server: 192.168.1.100 (开发服务器)
- data-gpu: lab-gpu-01.university.edu (GPU 计算节点)

## TTS
- 偏好声音: zh-CN-XiaoxiaoNeural

## 数据目录
- 财报原始数据: ~/data/earnings/
- 研报输出: ~/output/reports/

TOOLS.md 执行任务时可要求管家记录你和管家共同协作创建的工具，并在需要的时候前往工具目录阅读对应的 README 文件使用。

长期记忆

MEMORY.md

MEMORY.md 存放管家的长期记忆，下一节会详细展开它的存储和搜索机制。这里先看一个典型的文件内容：

# MEMORY.md - 长期记忆

## 关于用户
- 经济金融研究员，关注宏观经济与资产配置
- 偏好结构化产出（表格、要点、带数据支撑的结论）
- 不喜欢冗长的解释，直接给结论

## 项目记录
- 2026-04 PMI 季度分析：已完成数据清洗，下一步是趋势图
- 2026-03 行业研报：格式模板在 ~/templates/report.md

## 工作习惯
- 每周一上午整理上周数据
- 研报先出提纲再填内容

自动化任务

HEARTBEAT.md

HEARTBEAT.md 定义管家的周期性自动任务。心跳（heartbeat）功能默认每 30 分钟触发一次，管家会按照这个文件中的清单执行检查。

# Heartbeat Checklist

- 扫描收件箱，有无紧急消息
- 检查数据抓取脚本是否正常运行
- 白天时段做一次轻量签到

心跳也支持结构化的任务定义：

tasks:
  - name: 数据监控
    interval: 1h
    prompt: 检查 ~/data/feeds/ 目录，确认今日数据文件已到位

  - name: 邮件扫描
    interval: 30m
    prompt: 快速扫描收件箱，标记紧急邮件

如果 HEARTBEAT.md 内容为空（只有标题和空行），管家会跳过该轮心跳，不消耗资源。

索引式设计

上面介绍的 7 个配置文件有一个共同特点：大部分每轮都注入上下文。文件越长，每轮消耗的上下文越多。对于短期使用，这不是问题。但随着管家运行数月甚至数年，MEMORY.md 和 TOOLS.md 容易膨胀。

默认的写法是把这些文件当作”内容清单”：所有偏好、所有记忆、所有工具说明都直接写在文件里。这种方式直观但不可持续。

更优的设计是把配置文件当作索引：文件本身只记录最关键的信息和指向具体文件的链接。管家需要详细内容时，再按链接读取。

对比示例

以 MEMORY.md 为例，对比两种写法。

内容清单式（所有内容堆在一个文件中）：

# MEMORY.md

## 用户偏好
- 研报格式：标题用二级标题，数据用表格
- 图表配色：蓝灰色系
- 引用格式：APA 第 7 版
- 不喜欢饼图，偏好柱状图和折线图
- 数据精度：小数点后两位
- ...（随着时间推移，这个列表越来越长）

## 项目记录
- 2026-01 CPI 分析：结论是通胀温和
- 2026-02 就业数据：非农超预期
- 2026-03 行业研报：新能源板块
- 2026-04 PMI 分析：制造业 PMI 连续三月扩张
- ...（每个项目都记在这里）

## 常用模板
- 周报模板：...（完整模板内容）
- 月报模板：...（完整模板内容）

索引式（核心信息 + 指向具体文件的链接）：

# MEMORY.md - 长期记忆

## 关于用户
- 经济金融研究员，关注宏观经济与资产配置
- 偏好结构化产出（表格、要点、带数据支撑的结论）

## 上下文索引（按需查阅）
- 项目记录 → [projects/INDEX.md](projects/INDEX.md)
- 工作偏好 → [preferences/INDEX.md](preferences/INDEX.md)
- 常用任务模式 → [patterns/INDEX.md](patterns/INDEX.md)

索引式写法的 MEMORY.md 只有十几行，每轮注入消耗极少。管家在需要查看具体项目记录或偏好细节时，再通过链接读取对应文件。

三级索引

对于长期运行的管家，可以做三级索引结构：MEMORY.md（总入口）→ 类别索引（如 projects/INDEX.md）→ 具体文件（如 projects/pmi-2026q1.md）。这样无论积累多少内容，每轮注入的成本都保持恒定。TOOLS.md 也适用同样的设计：文件本身只列出工具类别和路径，具体配置放在各自的文件中。

这种设计的本质是区分”始终需要”和”按需加载”。始终需要的信息（用户身份、核心偏好）直接写在配置文件中。偶尔需要的信息（具体项目细节、历史记录）通过索引指向，用时再读取。

--- title: "23.1 OpenClaw 核心配置文件" --- ![OpenClaw 核心配置文件总览](images/img_01_config_files.png) OpenClaw 管家的所有配置都存放在一个工作区（workspace）目录中，默认路径为 `~/.openclaw/workspace`。工作区包含多种文件和子目录，本节聚焦其中最核心的 7 个配置文件。它们共同定义了管家是谁、如何工作、为谁服务。 ## 配置文件总览 | 文件 | 定位 | 每轮注入 | |:---|:---|:---:| | `IDENTITY.md` | 身份记录：名字、类型、emoji | 是 | | `SOUL.md` | 人格风格：语气、观点、幽默感 | 是 | | `USER.md` | 用户信息：称呼、时区、关注领域 | 是 | | `AGENTS.md` | 操作规则：行为边界、安全红线 | 是 | | `TOOLS.md` | 本地工具备忘：设备名称、偏好配置 | 是 | | `MEMORY.md` | 长期记忆：持久性事实与决策 | 仅主会话 | | `HEARTBEAT.md` | 心跳任务清单：周期性自动检查 | 仅心跳启用时 | ::: {.callout-note} ## 自动注入管家每次启动会话时，会将这些配置文件的内容注入对话上下文。`MEMORY.md` 仅在一对一会话中注入，群组对话中不加载，避免个人信息泄露。`HEARTBEAT.md` 只在心跳功能开启时才注入。 ::: 下面按职能分组介绍每个文件。 ## 身份与人格 ### IDENTITY.md `IDENTITY.md` 记录管家的基本身份信息。内容简短，通常在首次对话中生成。 ```txt # IDENTITY.md - Who Am I? Name: 小橙 Creature: AI 管家 Vibe: 温和、专注、偶尔冷幽默 Emoji: 🍊 Avatar: avatar.png ``` 这个文件回答一个问题：管家叫什么、是什么。名字和 emoji 会出现在对话界面中。 ### SOUL.md `SOUL.md` 定义管家的人格风格。如果说 `IDENTITY.md` 是"我是谁"，`SOUL.md` 就是"我怎么说话、怎么思考"。 ```txt # SOUL.md - Who You Are ## Core Truths - 简洁优先，不说废话 - 有观点，敢表达，但不固执 - 对用户坦诚，不迎合 ## Boundaries - 不编造数据 - 不假装知道不知道的事 ## Vibe - 像一个靠谱的同事：专业但不冷漠 - 回答控制在必要长度，不铺垫不总结 ## Continuity - 记住之前的讨论，不重复问已回答的问题 ``` `SOUL.md` 的写作原则是短而锐利。官方建议避免写成"企业手册风格"。每一条都应该能直接影响管家的语言行为。 ### USER.md `USER.md` 记录用户信息，让管家了解它在帮助谁。 ```txt # USER.md - About Your Human Name: 张明 What to call them: 张老师 Timezone: Asia/Shanghai ## Notes - 经济金融研究员，关注宏观经济与资产配置 - 偏好结构化产出（表格、要点、带数据支撑的结论） ## Context - 当前在做一个关于中国制造业 PMI 的季度分析项目 - 经常需要整理多个数据源的对比表格 ``` 这个文件随时间积累。管家越了解用户，越能提供贴合需求的帮助。 ## 操作规则 ### AGENTS.md `AGENTS.md` 是管家的操作规则文件，规定行为边界和安全约束。 ```txt # AGENTS.md - Your Workspace ## Session Startup - 会话开始时读取 MEMORY.md，了解上下文 - 检查是否有未完成的任务 ## Memory - 重要决策和事实写入 MEMORY.md - 不记录临时性、一次性的对话内容 ## Red Lines - 不在未经确认的情况下执行外部 API 调用 - 不删除用户文件 - 不发送消息给第三方 ## External vs Internal - 涉及外部操作（发邮件、调用 API）时先询问 - 内部操作（读文件、写笔记）可直接执行 ``` ::: {.callout-important} ## AGENTS.md 与 SOUL.md 的区分 `SOUL.md` 管"风格"：语气、观点、简洁度。`AGENTS.md` 管"规则"：什么能做、什么不能做、什么需要先问。一个是性格，一个是纪律。 ::: ## 工具备忘 ### TOOLS.md `TOOLS.md` 记录用户本地环境的具体信息，供管家在调用工具时参考。 ```txt # TOOLS.md - Local Notes ## SSH - dev-server: 192.168.1.100 (开发服务器) - data-gpu: lab-gpu-01.university.edu (GPU 计算节点) ## TTS - 偏好声音: zh-CN-XiaoxiaoNeural ## 数据目录 - 财报原始数据: ~/data/earnings/ - 研报输出: ~/output/reports/ ``` `TOOLS.md` 执行任务时可要求管家记录你和管家共同协作创建的工具，并在需要的时候前往工具目录阅读对应的 README 文件使用。 ## 长期记忆 ### MEMORY.md `MEMORY.md` 存放管家的长期记忆，下一节会详细展开它的存储和搜索机制。这里先看一个典型的文件内容： ```txt # MEMORY.md - 长期记忆 ## 关于用户 - 经济金融研究员，关注宏观经济与资产配置 - 偏好结构化产出（表格、要点、带数据支撑的结论） - 不喜欢冗长的解释，直接给结论 ## 项目记录 - 2026-04 PMI 季度分析：已完成数据清洗，下一步是趋势图 - 2026-03 行业研报：格式模板在 ~/templates/report.md ## 工作习惯 - 每周一上午整理上周数据 - 研报先出提纲再填内容 ``` ## 自动化任务 ### HEARTBEAT.md `HEARTBEAT.md` 定义管家的周期性自动任务。心跳（heartbeat）功能默认每 30 分钟触发一次，管家会按照这个文件中的清单执行检查。 ```txt # Heartbeat Checklist - 扫描收件箱，有无紧急消息 - 检查数据抓取脚本是否正常运行 - 白天时段做一次轻量签到 ``` 心跳也支持结构化的任务定义： ```txt tasks: - name: 数据监控 interval: 1h prompt: 检查 ~/data/feeds/ 目录，确认今日数据文件已到位 - name: 邮件扫描 interval: 30m prompt: 快速扫描收件箱，标记紧急邮件 ``` 如果 `HEARTBEAT.md` 内容为空（只有标题和空行），管家会跳过该轮心跳，不消耗资源。 ## 索引式设计上面介绍的 7 个配置文件有一个共同特点：大部分每轮都注入上下文。文件越长，每轮消耗的上下文越多。对于短期使用，这不是问题。但随着管家运行数月甚至数年，`MEMORY.md` 和 `TOOLS.md` 容易膨胀。默认的写法是把这些文件当作"内容清单"：所有偏好、所有记忆、所有工具说明都直接写在文件里。这种方式直观但不可持续。更优的设计是把配置文件当作索引：文件本身只记录最关键的信息和指向具体文件的链接。管家需要详细内容时，再按链接读取。 ### 对比示例以 `MEMORY.md` 为例，对比两种写法。内容清单式（所有内容堆在一个文件中）： ```txt # MEMORY.md ## 用户偏好 - 研报格式：标题用二级标题，数据用表格 - 图表配色：蓝灰色系 - 引用格式：APA 第 7 版 - 不喜欢饼图，偏好柱状图和折线图 - 数据精度：小数点后两位 - ...（随着时间推移，这个列表越来越长） ## 项目记录 - 2026-01 CPI 分析：结论是通胀温和 - 2026-02 就业数据：非农超预期 - 2026-03 行业研报：新能源板块 - 2026-04 PMI 分析：制造业 PMI 连续三月扩张 - ...（每个项目都记在这里） ## 常用模板 - 周报模板：...（完整模板内容） - 月报模板：...（完整模板内容） ``` 索引式（核心信息 + 指向具体文件的链接）： ```txt # MEMORY.md - 长期记忆 ## 关于用户 - 经济金融研究员，关注宏观经济与资产配置 - 偏好结构化产出（表格、要点、带数据支撑的结论） ## 上下文索引（按需查阅） - 项目记录 → [projects/INDEX.md](projects/INDEX.md) - 工作偏好 → [preferences/INDEX.md](preferences/INDEX.md) - 常用任务模式 → [patterns/INDEX.md](patterns/INDEX.md) ``` 索引式写法的 `MEMORY.md` 只有十几行，每轮注入消耗极少。管家在需要查看具体项目记录或偏好细节时，再通过链接读取对应文件。 ::: {.callout-tip} ## 三级索引对于长期运行的管家，可以做三级索引结构：`MEMORY.md`（总入口）→ 类别索引（如 `projects/INDEX.md`）→ 具体文件（如 `projects/pmi-2026q1.md`）。这样无论积累多少内容，每轮注入的成本都保持恒定。`TOOLS.md` 也适用同样的设计：文件本身只列出工具类别和路径，具体配置放在各自的文件中。 ::: 这种设计的本质是区分"始终需要"和"按需加载"。始终需要的信息（用户身份、核心偏好）直接写在配置文件中。偶尔需要的信息（具体项目细节、历史记录）通过索引指向，用时再读取。