文档
Agent 调教
工作区文件

工作区文件

工作区（workspace）是 Agent 的“家目录”：工具读写与工作区上下文都以它为中心。

它与 ~/.openclaw/ 不同：后者用于保存配置、凭据、会话等运行时数据。

默认位置

  • 默认：~/.openclaw/workspace
  • 若设置了 OPENCLAW_PROFILE（且不为 default），默认会变为 ~/.openclaw/workspace-<profile>
  • 也可以在 ~/.openclaw/openclaw.json 中覆盖：
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

openclaw onboard、openclaw configure 或 openclaw setup 会在需要时创建工作区，并为缺失的引导文件生成安全模板。

如果你完全自行管理这些文件，可关闭自动生成：

{ agent: { skipBootstrap: true } }

重要说明：工作区不是沙箱

工作区只是工具的默认 cwd。如果启用了沙箱（例如 Docker 沙箱），并且 workspaceAccess 不是 "rw"，工具会在 ~/.openclaw/sandboxes 下的沙箱工作区中运行，而不是直接操作宿主机的工作区。

相关：/docs/gateway/sandboxing/。

标准文件清单（工作区内）

常见结构如下（文件名以 .md 为准）：

~/.openclaw/workspace/
├── AGENTS.md        # 操作说明/优先级/如何使用记忆
├── SOUL.md          # 风格、边界、原则
├── USER.md          # 用户画像与称呼偏好
├── IDENTITY.md      # 名称/形象等（引导时生成/更新）
├── TOOLS.md         # 本机工具与约定的“说明”，不控制可用工具
├── HEARTBEAT.md     # 可选：心跳检查清单（尽量短）
├── BOOT.md          # 可选：网关重启时的启动清单（需内部 hooks）
├── BOOTSTRAP.md     # 一次性的首次引导（完成后可删除）
├── memory/          # 记忆日志（建议按天写入）
└── skills/          # 可选：工作区专属 skills（同名覆盖）

备份建议：私有 Git 仓库（推荐）

工作区经常包含“私密上下文”，建议仅备份到私有仓库。

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"

不要放进工作区的内容

以下内容应留在 ~/.openclaw/，并避免提交到工作区仓库：

  • ~/.openclaw/openclaw.json（配置）
  • ~/.openclaw/credentials/（OAuth token、API key 等）
  • ~/.openclaw/agents/<agentId>/sessions/（会话记录）
  • ~/.openclaw/skills/（托管/本地 skills）

下一步：/docs/concepts/agent-workspace/。

多 Agent 协作记忆（Memory）