---
title: "配置 Agent Workspace"
description: "理解 OpenClaw Agent Workspace：长期工作现场、标准启动文件、sandbox 边界、私有 git 备份和迁移方式。"
verifiedAt: "2026-05-06"
---

OpenClaw 的 workspace 是 Agent（智能代理）的长期工作现场。它放身份、人格、规则、工具说明、长期记忆和 workspace 级 skills。它不是 `~/.openclaw/`，也不是硬隔离 sandbox。

> [!NOTE]
> **这一章用 12 分钟换什么**：你会分清 workspace、配置目录、运行时状态、sandbox workspace、标准启动文件和 private git 备份；以后迁移机器时不会把密钥和 session 一起提交。

## 1. 先分清三类目录

新手最容易把三类目录混成一类：

| 目录 | 放什么 | 能不能进 git |
|------|------|------|
| Agent workspace | `AGENTS.md`、`SOUL.md`、`USER.md`、`TOOLS.md`、`MEMORY.md`、`memory/`、workspace skills | 可以，但应该是 private repo |
| `~/.openclaw/` | config、credentials、auth profiles、sessions、managed skills、runtime state | 不要整体进 git |
| sandbox workspace | sandbox 开启后给工具使用的隔离工作区 | 看 sandbox 策略，不等同于主 workspace |

workspace 是 Agent 的“工作现场”。`~/.openclaw/` 是 OpenClaw 的运行时系统目录。两者不要混。

```mermaid
flowchart TD
    Workspace["Agent Workspace"]
    Rules["启动规则和人格"]
    Memory["长期记忆"]
    Skills["Workspace skills"]
    State["~/.openclaw"]
    Config["配置和凭据"]
    Sessions["sessions / auth profiles"]
    Sandbox["Sandbox workspace"]
    Tools["工具执行现场"]

    Workspace --> Rules
    Workspace --> Memory
    Workspace --> Skills
    State --> Config
    State --> Sessions
    Sandbox --> Tools

    style Workspace fill:#dcfce7,stroke:#22c55e,stroke-width:2px
    style State fill:#fee2e2,stroke:#ef4444,stroke-width:2px
    style Sandbox fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
```

> [!IMPORTANT]
> **一句话区别**：workspace 是 Agent 读来工作的“家”；`~/.openclaw/` 是系统运行状态；sandbox workspace 是工具隔离执行时的工作区。

## 2. workspace 不是 sandbox

官方文档说得很直接：workspace 是 default cwd（默认工作目录），不是 hard sandbox（硬隔离边界）。工具的相对路径通常从 workspace 解析，但绝对路径仍可能访问主机其他位置，除非你配置了 sandbox。

如果启用了 sandbox，并且 `workspaceAccess` 不是 `"rw"`，工具会在 `~/.openclaw/sandboxes` 下的 sandbox workspace 里工作，而不是直接操作主机 workspace。

| 你以为 | 实际 |
|------|------|
| workspace 限制 Agent 只能访问这个目录 | 不是；它只是默认 cwd |
| `TOOLS.md` 能控制工具权限 | 不能；它只是说明文档 |
| 开 sandbox 后还一定操作主 workspace | 不一定；取决于 sandbox 的 workspace access |
| 把敏感内容放 workspace 里没事 | 不对；workspace 会进入 Agent 上下文 |

> [!WARNING]
> **权限控制靠配置和 sandbox，不靠目录名**：如果你要限制工具访问范围，去配置 sandbox 和 tool policy，不要指望 workspace 路径自动保护主机。

## 3. 默认位置和创建方式

默认 workspace 是：

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

如果设置了非 default 的 `OPENCLAW_PROFILE`，默认 workspace 会变成：

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

你也可以在配置里显式指定：

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

`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会创建 workspace，并在缺少标准文件时补齐启动文件。

如果你已经自己维护 workspace 文件，可以关闭 bootstrap 文件创建：

```json5
{ agents: { defaults: { skipBootstrap: true } } }
```

> [!TIP]
> **只保留一个 active workspace**：旧安装可能创建过 `~/openclaw`。多个 workspace 同时存在时，auth、记忆和状态很容易漂移。用 `openclaw doctor` 检查多余 workspace 提醒。

## 4. 标准文件地图

OpenClaw 会把 workspace 文件作为 Agent 上下文的一部分。每个文件应该只做一件事。

| 文件 / 目录 | 作用 | 新手写法 |
|------|------|------|
| `AGENTS.md` | 操作规则和长期约定 | 写任务优先级、工具使用方式、边界 |
| `SOUL.md` | 人格、语气、边界 | 写 Agent 应该像谁、怎么说话 |
| `USER.md` | 用户画像 | 写称呼、时区、偏好、长期背景 |
| `IDENTITY.md` | Agent 名称、符号、风格 | 写名片信息，不写密钥 |
| `TOOLS.md` | 本地工具约定 | 写工具说明，不当权限系统 |
| `HEARTBEAT.md` | 心跳检查清单 | 保持很短，避免 token 消耗 |
| `BOOT.md` | Gateway 重启后的启动检查 | 只写必要检查 |
| `BOOTSTRAP.md` | 第一次启动仪式 | 新 workspace 完成后可以删除 |
| `memory/YYYY-MM-DD.md` | 每日记忆日志 | 写当天观察、过程、待沉淀线索 |
| `MEMORY.md` | 长期记忆精华 | 只放未来会反复用到的事实 |
| `skills/` | workspace 级 skills | 同名时优先级最高 |
| `canvas/` | 可选 Canvas UI 文件 | 有明确 UI 需求再放 |

如果某个 bootstrap 文件缺失，OpenClaw 会把“缺失文件”标记注入 session，并继续运行。大文件会被截断；可以通过 `agents.defaults.bootstrapMaxChars` 和 `agents.defaults.bootstrapTotalMaxChars` 调整限制。

> [!TIP]
> **workspace 文件要分工，不要堆料**：规则放 `AGENTS.md`，人格放 `SOUL.md`，用户偏好放 `USER.md`，长期精华才进 `MEMORY.md`。

> [!CAUTION]
> **`MEMORY.md` 不要给共享群聊乱用**：长期记忆可能包含个人背景、偏好和敏感线索。共享或群聊上下文要单独设计。

## 5. 哪些内容不该进 workspace git

不要把 OpenClaw 运行时状态提交到 workspace 仓库。典型包括：

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

这些文件可能包含模型授权、渠道登录态、OAuth、session transcript、本机运行状态或 managed skills。迁移机器时可以单独处理，但不能当作普通内容同步。

最稳的判断方式：如果一个文件包含账号、token、OAuth、会话记录、浏览器登录态、模型授权或本机缓存，它就不是 workspace 内容。

## 6. 私有 git 备份怎么做

官方建议把 workspace 当作 private memory（私有记忆），用 private git 仓库备份。备份对象是规则、人格、身份、工具说明和长期记忆，不是运行时凭据。

新手可以从这些文件开始：

```bash
cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/
git commit -m "Add agent workspace"
```

`.gitignore` 至少排除：

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

> [!WARNING]
> **private repo 也不是密钥仓库**：私有仓库适合备份记忆和规则，不适合备份 API key、OAuth token、浏览器态和原始聊天转储。

## 7. 多 workspace 和迁移

多个 workspace 可以存在，但新手应该只保留一个 active workspace，并让 `agents.defaults.workspace` 明确指向它。

迁移到新机器时，按这个顺序做：

```mermaid
flowchart TD
    Clone["克隆 private workspace repo"]
    Config["更新 agents.defaults.workspace"]
    Setup["openclaw setup --workspace <path>"]
    Verify["openclaw doctor / gateway status"]
    Sessions["按需单独复制 sessions"]

    Clone --> Config
    Config --> Setup
    Setup --> Verify
    Verify --> Sessions

    style Clone fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Setup fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Verify fill:#dcfce7,stroke:#22c55e,stroke-width:2px
```

关键点：

- 先克隆 private workspace 仓库到目标路径。
- 再修改 `~/.openclaw/openclaw.json` 的 `agents.defaults.workspace`。
- 运行 `openclaw setup --workspace <path>` 补齐缺失文件。
- 历史 sessions 如确实需要，再单独复制 `~/.openclaw/agents/<agentId>/sessions/`。
- 多 Agent 场景可以拆 workspace，例如 personal、work、shared 分开。
- 共享 Agent 不要复用个人长期记忆 workspace。

## 8. 新手常见坑

- 以为 workspace 就是 sandbox：它只是默认工作目录，不是硬隔离。
- 把 `TOOLS.md` 当权限系统：它只是说明，权限要在配置和 sandbox 里控制。
- 把 `MEMORY.md` 暴露给群聊 Agent：长期记忆可能含有个人背景和敏感线索。
- 把 `~/.openclaw/` 整目录提交到 git：这会把运行时状态也带进去。
- 多个 workspace 同时改：Agent 行为会变得不可预测。
- 迁移时只复制 workspace，不处理配置指向：新机器可能仍然指向旧默认路径。
- 在 sandbox 打开后，还以为工具一定直接操作主 workspace。

## 9. 怎么验收

读完这一章，你应该能做到：

- 能说清 workspace 路径在哪里，以及 `~/.openclaw/` 里哪些内容不属于 workspace。
- 能打开标准文件，并知道每个文件解决什么问题。
- 能解释 workspace 为什么不是 sandbox。
- 能确认 private git 里没有 token、OAuth、session transcript、auth profile、`.env` 和本机缓存。
- 能在新机器上按同一个 workspace 路径启动，并让 OpenClaw 补齐缺失文件。
- 能为 shared Agent 使用独立 workspace，而不是复用个人长期记忆。

## 10. 本章自检

1. workspace、`~/.openclaw/`、sandbox workspace 分别放什么？
2. 为什么 workspace 不是安全隔离边界？
3. 哪些运行时文件不应该提交到 workspace git？

> [!IMPORTANT]
> **过关标准**：你能用一句话说清 —— “workspace 是 Agent 的长期工作现场，但权限、凭据、session 和运行时状态必须由配置目录、sandbox 和私有凭据体系分别管理。”

## 11. 接下来去哪

<Cards>
  <Card href="/docs/openclaw/official/01-gateway-runtime" title="Gateway 运行时" description="入门闭环完成后，继续理解 Gateway、Agent、Channel、安全和自动化。" />
  <Card href="/docs/openclaw/official/01-gateway-runtime/architecture" title="理解 Gateway 架构" description="从长期运行的控制面开始拆 OpenClaw 的运行时。" />
  <Card href="/docs/openclaw/understanding/06-workspace" title="理解：Workspace" description="从原理篇继续核对 workspace、memory、skills 和 sandbox 的边界。" />
</Cards>

## 12. 官方资料

- [Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [Memory overview](https://docs.openclaw.ai/concepts/memory)
- [SOUL.md personality guide](https://docs.openclaw.ai/concepts/soul)
- [Sandboxing](https://docs.openclaw.ai/gateway/sandboxing)
- [Session management](https://docs.openclaw.ai/concepts/session)
