Agent 工作区

理解 OpenClaw workspace 文件、agentDir、上下文注入、备份边界，以及 workspace guidance 与 memory 的区别。

OpenClaw Agent 会带着一个 workspace 运行：这里放人类可编辑的上下文文件，用来塑造 Agent 的行为。Workspace 是默认工作目录，不是安全沙盒。

Workspace 与 Agent Directory

OpenClaw 区分两类路径：

• Workspace：提示词和项目上下文，通常是 ~/.openclaw/workspace
• Agent directory：Agent 状态，例如 auth profiles、model registry、sessions，通常在 ~/.openclaw/agents/<agentId>/

多 Agent 场景下，每个 Agent 都应该有自己的 workspace 和 agent directory。不要让互相隔离的 Agent 复用同一个 agentDir。

如果 OPENCLAW_PROFILE 设置为非 default profile，默认 workspace 会变成 ~/.openclaw/workspace-<profile>。也可以通过 agents.defaults.workspace 覆盖。

标准 Workspace 文件

AGENTS.md

操作指令、优先级、工作流偏好，以及 Agent 应如何使用记忆。每个 session 都会加载，所以应该短、稳定、可执行。

# Operating Instructions

## Communication

- Reply in the user's language
- Keep chat-platform replies concise
- Ask before destructive or expensive actions

## Workflows

- Confirm timezone before scheduling
- Summarize long tool output before replying

SOUL.md

人格、语气和边界。这里放助手默认的表达风格和行为限制。每个 session 都会加载。

USER.md 与 IDENTITY.md

USER.md 放用户资料，例如时区和偏好。IDENTITY.md 描述 Agent 的名称、vibe 和展示信息。不要把 secrets 放进去。

TOOLS.md

工具使用说明。它不会授予工具权限，只是告诉 Agent 你希望它如何使用已有工具。

# Tool Notes

- Prefer read-only inspection before edits
- Use browser only when web_fetch is insufficient
- Ask before deleting files or sending external messages

HEARTBEAT.md 与 BOOT.md

HEARTBEAT.md 是可选的 heartbeat checklist。BOOT.md 是可选的启动 checklist，可在启用 internal hooks 后于 Gateway restart 时运行。

BOOTSTRAP.md

首次运行的 onboarding 问题和 setup ritual。它只应为全新的 workspace 创建，完成 ritual 后可以删除。

MEMORY.md

经整理的长期记忆：稳定事实、偏好、决策和短摘要。详细日志不要放这里，放到 daily memory notes。

memory/YYYY-MM-DD.md

每日记忆。今天和昨天会自动加载，memory/ 目录树会被 memory_search 和 memory_get 等工具索引。

DREAMS.md

可选的人类可读 memory consolidation 审阅输出。Dreaming 可以把整理结果写在这里，长期晋升仍写入 MEMORY.md。

skills/ 与 canvas/

skills/ 是 workspace-specific skills，优先级很高。canvas/ 是可选 Canvas UI 内容。

Workspace 不是 Memory

Workspace 文件是显式上下文。其中也包含一部分 memory 文件：

• MEMORY.md 是整理后的长期记忆
• memory/YYYY-MM-DD.md 是每日工作记忆
• QMD 或内置 backend 会索引 memory 以便召回
• active memory 可以在交互 session 中注入相关召回
• memory wiki 可以在主 memory 层旁边整理知识库

稳定规则放 workspace。学习到的事实、历史决策和跨会话召回放 memory 系统。

文件行为

• 空文件会被跳过
• 大文件可能在注入前被裁剪；磁盘上的原文件保持完整
• 缺失文件可能以 marker 形式出现
• 相对路径从 workspace 解析，但没有沙盒时，绝对路径仍可能访问宿主机其他位置
• 启用沙盒且限制 workspace access 时，文件工具可能在 ~/.openclaw/sandboxes 下的 sandbox workspace 里运行，而不是宿主 workspace

不属于 Workspace 的内容

这些内容不要当成 workspace 备份或 prompt context：

• ~/.openclaw/openclaw.json
• auth profiles 和 provider credentials
• ~/.openclaw/agents/<agentId>/sessions/ 下的 session JSONL
• ~/.openclaw/skills/ 下的 managed skills
• browser profiles、channel state 和 credential stores

备份

openclaw backup create --verify
openclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gz

同时把人类编写的 AGENTS.md、SOUL.md、USER.md、TOOLS.md、MEMORY.md、daily memory notes 和自定义 skills 放入版本控制。不要提交 API key、浏览器 profile、渠道状态、原始聊天、敏感附件或私密 transcript。

最佳实践

1. 保持 AGENTS.md 足够短，才能每轮都真正有用。
2. 把稳定 voice 和 boundaries 放进 SOUL.md。
3. 把工具偏好放进 TOOLS.md，不要写成工具百科。
4. 保持 MEMORY.md 精炼；详细 session 细节放进 memory/YYYY-MM-DD.md。
5. 一个 Agent persona 用一个 workspace。
6. 把 workspace access 当作 context engineering，不要当作租户隔离。