06 · Workspace：Agent 的工作空间和身份容器

前两篇分别讲 Memory 和 Context。这一篇讲它们共同依赖的物理位置：Agent workspace。

一句话先记住：

把这句话吃透，后面才不会把“文件规则”“运行配置”“会话历史”“安全隔离”混在一起。

1. Workspace 是什么

官方 Agent workspace 文档的定义是：

The workspace is the agent's home. It is the only working directory used for file tools and for workspace context.

默认位置：

~/.openclaw/workspace

如果设置了 OPENCLAW_PROFILE 且不是 default，默认会变成：

~/.openclaw/workspace-<profile>

也可以在 ~/.openclaw/openclaw.json 里覆盖：

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  }
}

openclaw onboard、openclaw configure、openclaw setup 会在缺文件时创建 workspace 并 seed bootstrap files。

2. Workspace 不是 ~/.openclaw/

这个边界很重要。

flowchart TD
  A[~/.openclaw/] --> B[openclaw.json]
  A --> C[credentials]
  A --> D[agents/<agentId>/sessions]
  A --> E[managed skills]
  A --> F[workspace]

  F --> G[AGENTS.md]
  F --> H[SOUL.md]
  F --> I[TOOLS.md]
  F --> J[MEMORY.md]
  F --> K[memory/YYYY-MM-DD.md]
  F --> L[skills/]

Workspace 里是 Agent 的可见工作材料。~/.openclaw/ 里还有运行配置、凭据、session transcripts、managed skills 等系统状态。

这意味着“复制 workspace”只能迁移一部分：规则、人格、用户资料、长期记忆、daily notes、workspace skills 可以随 workspace 迁移；openclaw.json、OAuth/API keys、channel credentials、sessions、managed skills 不在 workspace 里。

所以更准确的说法是：复制 workspace 可以迁移 Agent 的工作上下文和个性材料，但不能完整克隆运行态、凭据和历史会话。

3. Workspace 不是硬沙箱

官方警告非常关键：

The workspace is the default cwd, not a hard sandbox.

也就是说：

• 相对路径会以 workspace 为基准解析。
• 绝对路径仍可能访问 host 上其他位置。
• 如果需要隔离，必须启用 agents.defaults.sandbox 或 per-agent sandbox config。
• 启用 sandbox 且 workspaceAccess 不是 "rw" 时，tools 会在 ~/.openclaw/sandboxes 下的 sandbox workspace 里工作，而不是直接操作 host workspace。

flowchart TD
  A[Tool uses relative path] --> B[Resolve inside workspace]
  C[Tool uses absolute path] --> D[Can reach host path unless sandboxed]
  E[Sandbox enabled] --> F[Sandbox workspace under ~/.openclaw/sandboxes]

所以不要把 workspace 当作安全边界。它只是默认工作目录和上下文容器。真正的执行边界在 sandbox、tool policy、exec approvals 和 channel allowlists。

4. 标准文件地图

OpenClaw 期望 workspace 里有一组标准文件。它们不是随便命名的笔记，而是会影响 prompt、工具使用和会话行为的上下文文件。

如果 bootstrap file 缺失，OpenClaw 会注入 “missing file” marker 并继续；openclaw setup 可以补齐缺失默认文件，不覆盖已有文件。

5. AGENTS.md：操作规则

AGENTS.md 是 operating instructions。它适合写：

• Agent 的工作流程。
• 项目优先级。
• 不要做什么。
• 如何使用 memory。
• 遇到阻塞如何汇报。
• 哪些命令或目录是默认入口。

它不适合写：

• 情绪风格和人格。
• OAuth token 或 API key。
• 巨长历史记录。
• 临时任务流水账。

一个好 AGENTS.md 应该可执行、可检查、可更新。它不是品牌文案。

6. SOUL.md：声音、态度和边界

官方 SOUL guide 说：SOUL.md is where your agent's voice lives。

它适合写：

• tone。
• opinions。
• brevity。
• humor。
• boundaries。
• default level of bluntness。

它不适合写：

• life story。
• changelog。
• security policy dump。
• 没有行为效果的巨大情绪墙。

官方的原则很实用：Short beats long. Sharp beats vague.

换成中文就是：短比长好，明确比虚好。

SOUL.md 和 AGENTS.md 的分工：

人格不是放飞。官方也提醒：Personality is not permission to be sloppy。

7. TOOLS.md：工具约定，不是授权配置

这一点在前几篇反复出现，因为太容易错：

TOOLS.md does not control tool availability; it is only guidance.

适合写入 TOOLS.md 的内容：

• 本机工具路径。
• 常用命令说明。
• 工具使用顺序。
• 凭据在哪里取，但不要写凭据本身。
• 某些 CLI 的注意事项。

不适合写：

• “允许使用 exec”这类授权。
• token、密码、私钥。
• 大段教程全文。

工具是否能调用，由 tool policy、provider profile、sandbox policy 等硬边界决定。TOOLS.md 只能影响模型习惯。

8. MEMORY.md 和 memory/

MEMORY.md 是 curated long-term memory。workspace 文档特别说明：只在 main private session 加载，不应在 shared/group contexts 里随意加载。

memory/YYYY-MM-DD.md 是 daily memory log。官方建议 session start 时读今天和昨天。

结合前两篇，可以这样理解：

长期规则不要塞 daily note 后就期待每轮生效；临时状态也不要全部塞 MEMORY.md。

9. BOOTSTRAP.md 和 BOOT.md

这两个名字相近，但职责不同。

官方 bootstrapping 文档说，first run 会：

1. seed AGENTS.md、BOOTSTRAP.md、IDENTITY.md、USER.md。
2. 运行短 Q&A ritual。
3. 写 identity + preferences 到 IDENTITY.md、USER.md、SOUL.md。
4. 完成后移除 BOOTSTRAP.md，确保只跑一次。

如果你已经预置 workspace，可以跳过 bootstrap：

openclaw onboard --skip-bootstrap

或者在配置里设置：

{
  "agents": {
    "defaults": {
      "skipBootstrap": true
    }
  }
}

Bootstrapping 总是在 gateway host 上运行。如果 macOS app 连接的是远程 Gateway，workspace 文件也在远程机器上。

10. skills/ 是 workspace 级最高优先级

Workspace-specific skills 位于：

<workspace>/skills

它们在同名冲突时优先级最高，会覆盖 project agent skills、personal agent skills、managed skills、bundled skills 和 skills.load.extraDirs。

适合放 workspace skills 的场景：

• 某个 Agent 专属工作流。
• 某个项目独有工具 SOP。
• 不希望影响全局 Agent 的技能。
• 需要和 workspace 规则一起版本控制的流程。

不适合放：

• 全局通用技能。
• 含大量第三方依赖但没有审查的技能。
• 带密钥的脚本。

技能越贴近这个 workspace，越应该放这里；越通用，越应该放管理层级更高的位置。

11. 哪些东西不要进 workspace

官方明确列出这些不属于 workspace，也不应该提交到 workspace repo：

• ~/.openclaw/openclaw.json
• ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• ~/.openclaw/agents/<agentId>/agent/codex-home/
• ~/.openclaw/credentials/
• ~/.openclaw/agents/<agentId>/sessions/
• ~/.openclaw/skills/

原因很直接：config 是运行环境配置，不是 Agent 的工作记忆；credentials 包含 channel/provider/OAuth 状态；sessions 是历史 transcript 和 metadata，可能很大且敏感；managed skills 是全局或本机管理资产，不属于单个 workspace。

Workspace 可以做 private git backup，但仍然不要提交 secrets。即使是 private repo，也应避免 API keys、OAuth tokens、passwords、raw chats、敏感附件。

12. 推荐的私有备份方式

官方建议把 workspace 当作 private memory，放进私有 git repo 备份。

最小 .gitignore 可以包含：

.DS_Store
.env
**/*.key
**/*.pem
**/secrets*

备份时优先提交：

AGENTS.md
SOUL.md
TOOLS.md
IDENTITY.md
USER.md
HEARTBEAT.md
MEMORY.md
memory/
skills/

迁移到新机器时：

1. clone private repo 到目标路径。
2. 在 ~/.openclaw/openclaw.json 设置 agents.defaults.workspace。
3. 运行 openclaw setup --workspace <path> 补缺失文件。
4. 如果需要旧 session，再单独复制 ~/.openclaw/agents/<agentId>/sessions/。

不要把 workspace 迁移误解成完整系统迁移。配置和凭据要另行处理。

13. 常见误解

常见误解可以按这组边界校正：

• 复制 workspace 不等于完整克隆 Agent。它只能迁移工作上下文；config、credentials、sessions 不在里面。
• Workspace 不是沙箱。它只是默认 cwd；需要 sandbox 才有隔离。
• TOOLS.md 不能授权工具。它只是使用指导，工具可用性由 tool policy 控制。
• SOUL.md 不应该写所有规则。SOUL.md 管声音和边界，操作规则放 AGENTS.md。
• MEMORY.md 不是越全越好。太长会吃 context，应保存高信号长期事实。
• BOOTSTRAP.md 不应长期保留。它是 one-time first-run ritual，完成后删除。
• private git repo 也不应该放密钥。仍然不要提交 secrets。

14. 给 Agent 的实践任务

把下面任务交给你的 OpenClaw Agent：

请审查当前 workspace：
1. 列出 AGENTS.md、SOUL.md、USER.md、IDENTITY.md、TOOLS.md、HEARTBEAT.md、MEMORY.md、memory/、skills/ 是否存在。
2. 说明每个文件的职责，并指出是否有内容放错位置。
3. 检查是否有 API key、OAuth token、密码、私钥或 raw chat dump。
4. 用 /context list 检查是否有 bootstrap 文件被 TRUNCATED。
5. 给出一个最小 private git backup 清单，不包含 ~/.openclaw/openclaw.json、credentials、sessions。

重点看它有没有分清楚“规则文件”“运行配置”“凭据”“session 历史”和“沙箱边界”。

15. 本章自检

读完这一篇，你应该能回答：

1. Workspace 为什么是 Agent 的 home？
2. Workspace 和 ~/.openclaw/ 的边界是什么？
3. 为什么 workspace 不是硬沙箱？
4. AGENTS.md、SOUL.md、TOOLS.md 的职责差异是什么？
5. BOOTSTRAP.md 和 BOOT.md 的区别是什么？
6. skills/ 为什么是 workspace 级最高优先级？
7. 哪些文件不应该提交到 workspace repo？

能回答这些问题，再看下一篇多 Agent，才会理解为什么“给每个 Agent 一个 workspace”比“只换一个名字”重要。

16. 接下来去哪

17. 官方资料

• Agent Workspace
• Agent Runtime
• SOUL.md Personality Guide
• Agent Bootstrapping
• Context
• Memory Overview