配置 Agent Workspace

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

1. 先分清三类目录

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

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

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

2. workspace 不是 sandbox

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

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

3. 默认位置和创建方式

默认 workspace 是：

~/.openclaw/workspace

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

~/.openclaw/workspace-<profile>

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

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

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

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

{ agents: { defaults: { skipBootstrap: true } } }

4. 标准文件地图

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

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

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 仓库备份。备份对象是规则、人格、身份、工具说明和长期记忆，不是运行时凭据。

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

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 至少排除：

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

7. 多 workspace 和迁移

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

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

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？

11. 接下来去哪

12. 官方资料

• Agent workspace
• Memory overview
• SOUL.md personality guide
• Sandboxing
• Session management