配置 Agent Workspace

基于官方 OpenClaw workspace 教程，面向新手讲清 workspace、运行时状态、记忆文件、私有备份和迁移边界。

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

新手最容易混淆两件事：workspace 是 Agent 可以长期维护的“家”；~/.openclaw/ 是运行时系统状态，里面可能有密钥、登录态、sessions 和缓存。

先理解：workspace 不是什么

Workspace 不是安全隔离边界。工具的相对路径通常从 workspace 解析，但如果没有配置 sandbox，绝对路径仍可能访问主机其他位置。

如果你需要隔离，要配置 sandbox 和工具权限，而不是指望 workspace 路径自动限制一切。

Workspace 也不是凭据仓库。账号、OAuth、API key、渠道登录态、session transcript 不应该放进 workspace git。

默认位置和创建方式

默认 workspace 是 ~/.openclaw/workspace。如果使用非 default 的 OPENCLAW_PROFILE，默认会变成对应 profile 的 workspace。

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

你也可以在配置里指定 agents.defaults.workspace。多 Agent 场景中，也可以给不同 agent 分配不同 workspace，例如 home 和 work 分开。

标准文件地图

AGENTS.md 是操作规则，适合写任务优先级、工具使用方式、边界和长期约定。

SOUL.md 是人格和语气，回答这个 Agent 应该像谁、怎么说话、不能越过什么边界。

USER.md 是用户画像，适合写称呼、偏好、时区、长期背景。

IDENTITY.md 是 Agent 的名称、符号、风格和名片信息。

TOOLS.md 是本地工具约定。它只是指导，不等于权限控制；真正权限要靠配置、tools policy 和 sandbox。

HEARTBEAT.md 是心跳检查清单，应该短，避免每次心跳消耗太多上下文。

BOOT.md 是 Gateway 重启后的启动检查清单，通常和内部 hooks 配合。

BOOTSTRAP.md 是第一次启动仪式，只适合新 workspace，完成后可以删除。

memory/YYYY-MM-DD.md 是每日记忆日志，放当天原始观察、处理过程和待沉淀线索。

MEMORY.md 是长期记忆精华，只放未来会反复用到的事实和规则。官方建议不要把它暴露给共享或群聊上下文。

skills/ 是 workspace 级 skills。它的优先级高于项目、个人、托管、内置和额外目录里的同名 skill。

怎么判断哪些内容不该进 workspace git

不要把 OpenClaw 运行时状态提交到 workspace 仓库。典型包括配置文件、credentials、agent auth profiles、Codex home、sessions、全局 skills、模型授权和渠道登录态。

这些文件迁移机器时可以单独处理，但不能当作普通内容同步。公开仓库更不能放。

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

私有 git 备份怎么做

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

新手可以从这几个文件开始：AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md 和 memory/。

即便是 private repo，也要加 .gitignore，排除 .env、key、pem、secrets、临时文件和私密附件。

多 workspace 和迁移

多个 workspace 同时存在会让 auth、记忆和状态漂移。新手应该只保留一个 active workspace，并让 agents.defaults.workspace 明确指向它。

迁移到新机器时，先克隆私有 workspace 仓库，再修改 ~/.openclaw/openclaw.json 的 workspace 指向，然后运行 setup 补齐缺失文件。历史 sessions 如确实需要，再单独复制运行时 sessions 路径。

多 Agent 场景可以拆 workspace。比如 personal、work、shared 分开。共享 Agent 不要复用个人 workspace。

新手常见坑

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

怎么验收

你能说清 workspace 路径在哪里，以及 ~/.openclaw/ 里哪些内容不属于 workspace。

你能打开标准文件，并知道每个文件解决什么问题。

你能确认 private git 里没有 token、OAuth、session transcript、auth profile、.env 和本机缓存。

你能在新机器上按同一个 workspace 路径启动，并让 OpenClaw 补齐缺失文件。

你能为 shared Agent 使用独立 workspace，而不是复用个人长期记忆。