openclaw-workspace

OpenClaw 工作区技能

概述

OpenClaw 工作区文件构成了 Agent 的“灵魂与记忆”——每轮对话（或相关轮次）都会将它们注入系统提示词，为 Agent 提供身份、行为规则、环境知识和长期记忆。妥善管理这些文件至关重要：内容膨胀会浪费令牌，冗余会造成混乱，过时内容则会导致错误决策。

**令牌预算：**每个文件最多 20,000 个字符，所有引导文件合计约 150,000 个字符。

文件清单

文件	用途	加载时机	子 Agent？
AGENTS.md	启动顺序、检查清单、行为规则	每轮对话（所有 Agent）	是
SOUL.md	人设、语气、价值观、连续性理念	每轮对话（所有 Agent）	是
TOOLS.md	特定环境的说明（SSH、TTS、摄像头、设备）	按需参考（属于引导文件集的一部分）	是
USER.md	用户档案、偏好、关系背景	每轮对话（所有 Agent）	是
IDENTITY.md	名称、表情符号、头像、自我描述	每轮对话	是
HEARTBEAT.md	定期检查任务和健康例程	每次心跳轮次	视情况而定
BOOT.md	启动操作（需要 hooks.internal.enabled）	网关启动时	否
BOOTSTRAP.md	首次使用引导脚本——使用后删除	仅限新工作区	否
MEMORY.md	长期整理的事实和铁律	仅主会话	否
memory/YYYY-MM-DD.md	每日会话日志	根据 AGENTS.md 启动顺序加载	否
checklists/*.md	分步运维指南	在 AGENTS.md 中引用，按需加载	否

**安全规则：**绝不能在群聊或子 Agent 会话中加载 MEMORY.md——其中包含不应泄露的私密上下文。

如需了解各文件的设计、反模式和章节结构的完整详情，请参阅 references/workspace-files.md。

工作区路径

路径	用途
~/.openclaw/workspace/	主 Agent 的默认工作区
~/.openclaw/workspace-<profile>/	每个配置文件对应的工作区（多个 Agent）
~/.openclaw/workspace/vendor/OpenClaw-Memory/	供应商管理的基础文件（与上游同步）
~/.openclaw/workspace/checklists/	AGENTS.md 中引用的检查清单文件
~/.openclaw/workspace/memory/	每日会话日志
~/.openclaw/workspace/docs/	按需加载的文档（不会自动加载）

配置键：agents.defaults.workspace 或每个 Agent 对应的 agents.list[].workspace。

工作流：审查现有工作区

当工作区文件可能存在内容膨胀、过时或冗余时使用。

1. 读取所有启用的文件——AGENTS.md、SOUL.md、TOOLS.md、USER.md、IDENTITY.md、HEARTBEAT.md、BOOT.md、MEMORY.md
2. 检查字符数：

   wc -c ~/.openclaw/workspace/AGENTS.md
   wc -c ~/.openclaw/workspace/SOUL.md
   wc -c ~/.openclaw/workspace/TOOLS.md
   wc -c ~/.openclaw/workspace/USER.md
   wc -c ~/.openclaw/workspace/IDENTITY.md
   wc -c ~/.openclaw/workspace/MEMORY.md
   # Or all at once:
   wc -c ~/.openclaw/workspace/*.md
   

3. 标记超过 10,000 个字符的文件——这些文件最适合精简或移至 docs/
4. 检查冗余——SOUL.md 和 AGENTS.md 中是否有相同事实？TOOLS.md 和 MEMORY.md 中是否有相同工具说明？
5. 检查过时内容——过时的 SSH 主机、旧工具名称、已弃用的规则、不再需要的历史背景
6. 检查 MEMORY.md 的内容管理——应包含整理过的事实、经验教训、决策和关键规则，而非原始会话摘要或特定任务的备注
7. 提出有针对性的编辑建议——精简、移至 docs/ 或重新组织

具体优化策略请参阅 references/optimization-guide.md。

工作流：设置新工作区

从零开始为新 Agent 创建工作区时使用。

文件创建顺序（这关系到启动序列能否正常运行）：

1. SOUL.md — 首先定义角色设定和价值观；其他内容都以此身份为基础
2. AGENTS.md — 启动序列、安全规则、检查清单表
3. IDENTITY.md — 名称、表情符号、头像
4. USER.md — 人类用户的资料和偏好（仅主 Agent 使用）
5. TOOLS.md — 特定环境的说明（随着发现环境详情逐步添加）
6. MEMORY.md — 从精简内容开始；只记录真正通用的铁律
7. HEARTBEAT.md — 定期健康检查（可选，需要时添加）
8. BOOT.md — 启动钩子（可选，仅当 hooks.internal.enabled = true 时添加）
9. BOOTSTRAP.md — 首次运行引导（可选；首次成功启动后删除）

最小可用工作区： AGENTS.md + SOUL.md + TOOLS.md。其他内容均为可选。

BOOTSTRAP.md 注意事项： 如果创建 BOOTSTRAP.md，请在末尾加入自删除指令：

## Final Step
Delete this file: exec `rm ~/.openclaw/workspace/BOOTSTRAP.md`

工作流：提炼记忆

定期使用（每周或每月），以保持 MEMORY.md 精简。

1. 阅读所有近期的每日日志： 过去一段时间内的 memory/YYYY-MM-DD.md 文件
2. 找出适合提升到 MEMORY.md 的内容：
   • 不止一次违反的规则（反复出现的错误）
   • 技能文档中尚未记录、来之不易的发现
   • 应始终保留在上下文中的特定环境事实（不应只依赖 memory_search 回忆）
3. 检查 MEMORY.md 中已有的内容 — 避免重复
4. 起草补充内容 — 使用铁律格式：简洁、以行动为导向、含义明确
5. 归档旧的每日日志 — 将超过 30 天的文件移至 memory/archive/ 或删除
6. 检查 MEMORY.md 的总大小 — 保持在 10,000 个字符以内；如果超出，请检查是否有规则已足够稳定，可以移至某个技能的 SKILL.md

不要将以下内容写入 MEMORY.md：

• 长篇叙述或会话摘要
• 技能文档中已有的内容
• 只与某个过去任务有关的内容
• 情节性或特定任务的记忆（改用 memory_search/SQLite 存储）

工作流：添加或更新检查清单

添加新的高风险操作类型或更新现有检查清单时使用。

1. 创建或编辑 checklists/<operation-name>.md
2. 结构：

   # Checklist: <Operation Name>
   
   ## Pre-flight
   - [ ] Step 1
   - [ ] Step 2
   
   ## Execution
   - [ ] Step 3
   
   ## Verification
   - [ ] Confirm outcome
   - [ ] Log result in memory
   

3. 在 AGENTS.md 中登记 — 在检查清单表中添加一行：

   | <Operation description> | `checklists/<filename>.md` |
   

4. 保持检查清单简短 — 如果检查清单超过约 50 行，它可能是在编写文档；将叙述性内容移至 docs/，只保留可执行的步骤

工作流：更新 TOOLS.md

添加新工具、设备或环境功能时使用。

TOOLS.md = 特定环境的速查表。 应包含：

• 此设备的 SSH 主机和常用命令
• TTS 提供方、语音 ID 及相关注意事项
• 此配置的摄像头 ID 或设备名称
• Node 设备 ID 或名称
• 不明显的本地别名或快捷方式

不要将以下内容写入 TOOLS.md：

• 通用技能文档（使用技能的 SKILL.md 文件）
• 所有环境中都相同的内容
• 安装说明（使用 docs/）

格式约定：

# TOOLS.md - Local Notes

## SSH
- Main server: `ssh user@hostname`

## TTS
- Provider: Edge
- Voice: zh-CN-XiaoxiaoNeural

## Cameras
- Living room: node-id `abc123`, device `camera-0`

常见问题

文件超过令牌限制

症状： 文件超过 20,000 个字符；OpenClaw 可能会截断文件。 修复： 检查是否有内容应放入 docs/（按需加载），而非引导文件。将详细参考资料、历史背景和长篇示例移出。只保留每轮都需要的内容。

MEMORY.md 泄露到群组

症状： Agent 在群聊或 Discord 中分享私人上下文。 修复： 确保 AGENTS.md 中 MEMORY.md 的启动步骤设有门控：“仅主会话：读取 MEMORY.md”。确认 Agent 的启动序列会在加载前明确检查会话类型。

启动序列未加载文件

症状： 会话开始时，Agent 不知道 SOUL.md、USER.md 或 MEMORY.md 中的内容。 修复： 检查 AGENTS.md 启动序列是否明确列出每个要读取的文件。Agent 不会自动加载文件，而是遵循 AGENTS.md 中的启动序列说明。如果使用 BOOT.md，请确认配置中的 hooks.internal.enabled = true。

MEMORY.md 变得过大

症状： 文件接近或超过 10,000 个字符；每轮都读取会浪费大量上下文。 修复： 运行记忆提炼工作流。将数月来一直未出问题的稳定规则移至相关技能的 SKILL.md 文件中。删除不再相关的规则。

工作区更改未生效

症状： 编辑工作区文件后，Agent 仍在使用旧内容。 修复： 工作区文件会根据启动序列在会话开始时读取。重启网关或开始新会话，使更改生效。

参考文件

参考资料	涵盖内容
workspace-files.md	深入介绍各个文件：用途、设计原则、反模式和章节结构
optimization-guide.md	Token 效率策略、审计命令和提炼流程