---
title: "06 · Workspace：Agent 的工作空间和身份容器"
description: "讲清 OpenClaw workspace 的真实边界：它是默认 cwd 和项目上下文，不是配置库、凭据库或硬沙箱。"
verifiedAt: "2026-05-06"
---

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

一句话先记住：

> [!TIP]
> Workspace 是 Agent 的家目录，是 file tools 的默认工作目录，也是 workspace context 的来源；但它不是 `~/.openclaw/`，不是凭据库，也不是硬沙箱。

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

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

默认位置：

```text
~/.openclaw/workspace
```

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

```text
~/.openclaw/workspace-<profile>
```

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

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

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

## 2. Workspace 不是 `~/.openclaw/`

这个边界很重要。

```mermaid
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。

```mermaid
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。

> [!WARNING]
> Workspace 只是默认 cwd。需要安全隔离时，要看 sandbox、tool policy、exec approvals 和 channel allowlists。

## 4. 标准文件地图

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

| 文件或目录 | 官方定位 | 实践边界 |
| --- | --- | --- |
| `AGENTS.md` | Operating instructions for the agent and memory usage | 写工作规则、优先级、行为约束 |
| `SOUL.md` | Persona, tone, boundaries | 写声音、态度、边界，不写操作手册 |
| `USER.md` | Who the user is and how to address them | 写用户资料和称呼偏好 |
| `IDENTITY.md` | Agent name, vibe, emoji | 写名称和外在身份 |
| `TOOLS.md` | Local tool conventions | 只写工具使用约定，不控制工具可用性 |
| `HEARTBEAT.md` | Tiny checklist for heartbeat runs | 写短巡检清单，避免 token burn |
| `BOOT.md` | Startup checklist on gateway restart when internal hooks enabled | 写网关启动后的短动作 |
| `BOOTSTRAP.md` | One-time first-run ritual | 只在新 workspace 首次入职用，完成后删除 |
| `MEMORY.md` | Curated long-term memory | 写长期事实、偏好、决策 |
| `memory/YYYY-MM-DD.md` | Daily memory log | 写每天的运行观察和短期记录 |
| `skills/` | Workspace-specific skills | workspace 级最高优先级技能 |
| `canvas/` | Canvas UI files | node displays 相关 UI 文件 |

如果 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` 的分工：

| 需求 | 放哪里 |
| --- | --- |
| “回答要短，不要客服腔” | `SOUL.md` |
| “改文件前先跑测试” | `AGENTS.md` |
| “遇到用户错误假设要直接指出” | `SOUL.md` |
| “发布前必须执行 `pnpm build`” | `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` 只能影响模型习惯。

> [!IMPORTANT]
> `TOOLS.md` 能告诉 Agent 怎么用工具，不能授予工具权限。授权永远看 tool policy。

## 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 时读今天和昨天。

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

| 层 | 用途 | 风险 |
| --- | --- | --- |
| `MEMORY.md` | 长期稳定事实 | 太长会增加 context 压力 |
| `memory/YYYY-MM-DD.md` | 每日工作观察 | 旧文件需要搜索召回 |
| `DREAMS.md` | Dreaming human review surface | 不等同长期记忆 |

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

## 9. `BOOTSTRAP.md` 和 `BOOT.md`

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

| 文件 | 触发时机 | 做什么 |
| --- | --- | --- |
| `BOOTSTRAP.md` | brand-new workspace 的 first-run ritual | 收集身份信息，写入 `IDENTITY.md`、`USER.md`、`SOUL.md`，完成后删除 |
| `BOOT.md` | gateway restart，且 internal hooks 启用时 | 运行短启动清单 |

官方 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：

```bash
openclaw onboard --skip-bootstrap
```

或者在配置里设置：

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

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

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

Workspace-specific skills 位于：

```text
<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` 可以包含：

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

备份时优先提交：

```text
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：

```text
请审查当前 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. 接下来去哪

<Cards>
  <Card href="/docs/openclaw/understanding/07-multi-agent" title="07 · 多 Agent" description="继续看不同 workspace、不同模型、不同权限和不同会话入口如何组合。" />
  <Card href="/docs/openclaw/understanding/05-context-management" title="05 · Context 管理" description="回到 context 篇，确认 workspace 文件如何被注入、截断和计入窗口。" />
  <Card href="/docs/openclaw/official/00-getting-started/workspace" title="官方教程：Workspace" description="对照官方 Workspace 页继续核对标准文件、私有备份和迁移边界。" />
</Cards>

## 17. 官方资料

- [Agent Workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [Agent Runtime](https://docs.openclaw.ai/concepts/agent)
- [SOUL.md Personality Guide](https://docs.openclaw.ai/concepts/soul)
- [Agent Bootstrapping](https://docs.openclaw.ai/concepts/bootstrapping)
- [Context](https://docs.openclaw.ai/concepts/context)
- [Memory Overview](https://docs.openclaw.ai/concepts/memory)
