# Agent 工作区

> Agent 工作区：位置、布局和备份策略

- 网址：https://funcoding.ai/agents/openclaw/concepts/agent-workspace/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/concepts/agent-workspace

---
工作区是智能体的主目录：文件工具和工作区上下文所使用的工作目录。请将其保密，并把它视为记忆。

它与 `~/.openclaw/` 相互独立，后者存储配置、凭据和会话。

<div class="callout callout-warning">

工作区是**默认 cwd**，而不是严格的沙箱。工具会基于工作区解析相对路径，但除非启用沙箱隔离，否则绝对路径仍可访问主机上的其他位置。如果需要隔离，请使用 [`agents.defaults.sandbox`](https://funcoding.ai/agents/openclaw/gateway/sandboxing/)（和/或按 Agent 配置的沙箱配置）。

启用沙箱隔离且 `workspaceAccess` 不是 `"rw"` 时，工具会在 `~/.openclaw/sandboxes` 下的沙箱工作区内运行，而不是在你的主机工作区内运行。

</div>

## 默认位置

- 默认值：`~/.openclaw/workspace`
- 如果已设置 `OPENCLAW_PROFILE` 且其值不是 `"default"`，默认值将变为 `~/.openclaw/workspace-<profile>`。
- 设置后，`OPENCLAW_WORKSPACE_DIR` 会覆盖上述两项。
- 没有显式工作区的非默认智能体（`agents.entries.*`）会解析到 `<state-dir>/workspace-<agentId>`，而不是共享的默认工作区。

在 `~/.openclaw/openclaw.json` 中覆盖：

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

按 Agent 覆盖：`agents.entries.*.workspace`。

如果工作区或引导文件不存在，`openclaw onboard`、`openclaw configure` 或 `openclaw setup` 会创建工作区并填充引导文件。

<div class="callout callout-note">

沙箱种子复制只接受工作区内的常规文件；解析到源工作区之外的符号链接或硬链接别名会被忽略。

</div>

如果你已经自行管理工作区文件，请禁用引导文件创建：

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

## 额外工作区文件夹

较旧的安装可能已创建 `~/openclaw`。保留多个工作区目录可能导致令人困惑的身份验证或状态漂移，因为同一时间只有一个工作区处于活动状态。

<div class="callout callout-note">

**建议：**只保留一个活动工作区。如果你不再使用额外的文件夹，请将其归档或移至废纸篓（例如 `trash ~/openclaw`）。如果你有意保留多个工作区，请确保 `agents.defaults.workspace`（或按 Agent 配置的 `workspace` 键）指向活动工作区。

</div>

## 工作区文件映射

OpenClaw 预期工作区内包含的标准文件：

<details>
<summary>AGENTS.md - 操作说明</summary>

智能体的操作说明以及它应如何使用记忆。每个会话开始时加载。适合存放规则、优先级和“行为方式”详情。

</details>

<details>
<summary>SOUL.md - 人格和语气</summary>

人格、语气和边界。每个会话都会加载。指南：[SOUL.md 人格指南](https://funcoding.ai/agents/openclaw/concepts/soul/)。

</details>

<details>
<summary>USER.md - 用户身份</summary>

用户是谁以及应如何称呼他们。每个会话都会加载。

</details>

<details>
<summary>IDENTITY.md - 名称、风格和表情符号</summary>

智能体的名称、风格和表情符号。在引导仪式期间创建或更新。

</details>

<details>
<summary>TOOLS.md - 本地工具约定</summary>

关于本地工具和约定的说明。它不控制工具可用性；仅用于提供指导。

</details>

<details>
<summary>HEARTBEAT.md - Heartbeat 检查清单</summary>

用于 Heartbeat 运行的可选精简检查清单。请保持简短，以避免消耗过多 token。

</details>

<details>
<summary>BOOT.md - 启动检查清单</summary>

Gateway 网关重启时自动运行的可选启动检查清单（启用[内部钩子](https://funcoding.ai/agents/openclaw/automation/hooks/)时）。请保持简短；使用消息工具发送出站消息。

</details>

<details>
<summary>BOOTSTRAP.md - 首次运行仪式</summary>

仅执行一次的首次运行仪式。只会为全新的工作区创建。仪式完成后将其删除。

</details>

<details>
<summary>memory/YYYY-MM-DD.md - 每日记忆日志</summary>

每日记忆日志（每天一个文件）。建议在会话开始时阅读今天和昨天的日志。

</details>

<details>
<summary>MEMORY.md - 精选长期记忆（可选）</summary>

精选长期记忆：持久事实、偏好、决策和简短摘要。将详细日志保存在 `memory/YYYY-MM-DD.md` 中，以便记忆工具按需检索，而不必将其注入每个提示词。仅在私密的主会话中加载 `MEMORY.md`（不在共享或群组上下文中加载）。有关工作流程和自动记忆刷新的信息，请参阅[记忆](https://funcoding.ai/agents/openclaw/concepts/memory/)。

</details>

<details>
<summary>skills/ - 工作区 Skills（可选）</summary>

工作区专用 Skills。当名称冲突时，这是该工作区中优先级最高的 Skills 位置，优先于项目智能体 Skills、个人智能体 Skills、托管 Skills、内置 Skills 和 `skills.load.extraDirs`。

</details>

<details>
<summary>canvas/ - Canvas UI 文件（可选）</summary>

用于节点显示的 Canvas UI 文件（例如 `canvas/index.html`）。

</details>

<div class="callout callout-note">

如果缺少引导文件，OpenClaw 会向会话中注入“文件缺失”标记并继续运行。注入时会截断过大的引导文件；可通过 `agents.defaults.bootstrapMaxChars`（默认值：`20000`）和 `agents.defaults.bootstrapTotalMaxChars`（默认值：`60000`）调整限制。`openclaw setup` 可以重新创建缺失的默认文件，而不会覆盖现有文件。

</div>

## 工作区中不包含的内容

以下内容位于 `~/.openclaw/` 下，不应提交到工作区仓库：

- `~/.openclaw/openclaw.json`（配置）
- `~/.openclaw/state/openclaw.sqlite`（共享工作区设置状态和证明）
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（模型身份验证配置文件：OAuth + API 密钥）
- `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`（会话行、对话记录和按 Agent 配置的运行时状态）
- `~/.openclaw/agents/<agentId>/agent/codex-home/`（按 Agent 配置的 Codex 运行时账户、配置、Skills、插件和原生线程状态）
- `~/.openclaw/credentials/`（渠道/提供商状态以及旧版 OAuth 导入数据）
- `~/.openclaw/agents/<agentId>/sessions/`（旧版迁移源和归档/支持工件）
- `~/.openclaw/skills/`（托管 Skills）

如果需要迁移会话或配置，请单独复制它们，并将其排除在版本控制之外。

较旧的 OpenClaw 版本会写入工作区附属文件 `openclaw-workspace-state.json`、
`.openclaw/workspace-state.json` 和 `.attested`。当前
运行时仅使用共享 SQLite 数据库保存该状态。如果 Doctor 报告
其中一个文件，请运行 `openclaw doctor --fix`；Doctor 会导入有效的旧版
状态，并且仅在验证数据库行后才删除源文件。

## Git 备份（建议使用私有仓库）

将工作区视为私密记忆。请将其放入**私有** Git 仓库，以便备份和恢复。

在运行 Gateway 网关的计算机上执行以下步骤（工作区就在该计算机上）。

**初始化仓库**

如果已安装 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"
```

**添加私有远程仓库**

**GitHub Web UI**

1. 在 GitHub 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程仓库并推送：

```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```

**GitHub CLI (gh)**

```bash
gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push
```

**GitLab Web UI**

1. 在 GitLab 上创建一个新的**私有**仓库。
2. 不要使用 README 初始化（避免合并冲突）。
3. 复制 HTTPS 远程 URL。
4. 添加远程仓库并推送：

```bash
git branch -M main
git remote add origin <https-url>
git push -u origin main
```

**持续更新**

```bash
git status
git add .
git commit -m "Update memory"
git push
```

## 不要提交密钥

<div class="callout callout-warning">

即使是私有仓库，也应避免在工作区中存储密钥：

- API 密钥、OAuth token、密码或私密凭据。
- `~/.openclaw/` 下的任何内容。
- 聊天或敏感附件的原始转储。

如果必须存储敏感引用，请使用占位符，并将真正的密钥保存在其他位置（密码管理器、环境变量或 `~/.openclaw/`）。

</div>

建议的 `.gitignore` 初始内容：

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

## 将工作区迁移到新计算机

**克隆仓库**

将仓库克隆到所需路径（默认路径为 `~/.openclaw/workspace`）。

**更新配置**

在 `~/.openclaw/openclaw.json` 中将 `agents.defaults.workspace` 设置为该路径。

**填充缺失文件**

运行 `openclaw setup --workspace <path>` 以填充所有缺失文件。

**复制会话（可选）**

如果需要会话，请单独从旧计算机复制 `~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`。
仅当还需要旧版迁移输入或归档/支持工件时，才复制 `~/.openclaw/agents/<agentId>/sessions/`。

## 高级说明

- 多智能体路由可通过 `agents.entries.*.workspace` 为每个智能体使用不同的工作区。有关路由配置，请参阅[频道路由](https://funcoding.ai/agents/openclaw/channels/channel-routing/)。
- 如果启用了 `agents.defaults.sandbox`，非主会话可以使用 `agents.defaults.sandbox.workspaceRoot` 下的按会话沙箱工作区。

## 相关内容

- [Heartbeat](https://funcoding.ai/agents/openclaw/gateway/heartbeat/) - HEARTBEAT.md 工作区文件
- [沙箱隔离](https://funcoding.ai/agents/openclaw/gateway/sandboxing/) - 沙箱隔离环境中的工作区访问
- [会话](https://funcoding.ai/agents/openclaw/concepts/session/) - 会话存储路径
- [常设指令](https://funcoding.ai/agents/openclaw/automation/standing-orders/) - 工作区文件中的持久指令