Agent Workspace

Workspace 是 Agent 的家。它是文件工具和 workspace context 使用的唯一工作目录。把它当作私密空间和记忆来对待。

这与 ~/.openclaw/ 是分开的，后者存储配置、凭证和 session。

重要提示： Workspace 是默认工作目录，而不是硬性沙箱。工具会根据 workspace 解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱。如果你需要隔离，请使用 agents.defaults.sandbox（和/或单个 agent 的 sandbox 配置）。当启用沙箱且 workspaceAccess 不是 "rw" 时，工具会在 ~/.openclaw/sandboxes 下的 sandbox workspace 中运行，而不是你的主机 workspace。

默认位置

  • 默认：~/.openclaw/workspace
  • 如果设置了 OPENCLAW_PROFILE 且不是 "default"，默认位置会变成 ~/.openclaw/workspace-<profile>。
  • 在 ~/.openclaw/openclaw.json 中覆盖：
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

openclaw onboard、openclaw configure 或 openclaw setup 会创建 workspace 并在缺失时生成 bootstrap 文件。

如果你已经自己管理 workspace 文件，可以禁用 bootstrap 文件创建：

{ agent: { skipBootstrap: true } }

额外的 workspace 文件夹

旧版本安装可能创建了 ~/openclaw。保留多个 workspace 目录会导致混乱的认证或状态漂移，因为同一时间只有一个 workspace 是活动的。

建议： 只保留一个活动的 workspace。如果你不再使用额外的文件夹，可以归档或移到回收站（例如 trash ~/openclaw）。如果你有意保留多个 workspace，确保 agents.defaults.workspace 指向活动的那个。

openclaw doctor 会在检测到额外的 workspace 目录时发出警告。

Workspace 文件说明（每个文件的作用）

这些是 OpenClaw 在 workspace 中期望的标准文件：

  • AGENTS.md

    • Agent 的操作指南以及如何使用记忆。
    • 在每个 session 开始时加载。
    • 适合放置规则、优先级和”如何行为”的细节。

  • SOUL.md

    • 人格、语气和边界。
    • 每个 session 都会加载。

  • USER.md

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

  • IDENTITY.md

    • Agent 的名字、氛围和 emoji。
    • 在 bootstrap 仪式期间创建/更新。

  • TOOLS.md

    • 关于你本地工具和约定的笔记。
    • 不控制工具可用性；仅作为指导。

  • HEARTBEAT.md

    • 可选的 heartbeat 运行小清单。
    • 保持简短以避免 token 消耗。

  • BOOT.md

    • 可选的启动清单，在启用内部钩子时于 gateway 重启时执行。
    • 保持简短；使用 message 工具进行对外发送。

  • BOOTSTRAP.md

    • 一次性首次运行仪式。
    • 仅为全新 workspace 创建。
    • 仪式完成后删除它。

  • memory/YYYY-MM-DD.md

    • 每日记忆日志（每天一个文件）。
    • 建议在 session 开始时读取今天和昨天的记录。

  • MEMORY.md（可选）

    • 精选的长期记忆。
    • 仅在主要的私密 session 中加载（不在共享/群组上下文中）。

查看 Memory 了解工作流程和自动记忆刷新。

  • skills/（可选）

    • Workspace 专属的 skill。
    • 当名称冲突时会覆盖托管的/捆绑的 skill。

  • canvas/（可选）

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

如果任何 bootstrap 文件缺失，OpenClaw 会在 session 中注入一个”缺失文件”标记并继续。大型 bootstrap 文件在注入时会被截断；可以用 agents.defaults.bootstrapMaxChars 调整限制（默认：20000）。openclaw setup 可以重新创建缺失的默认文件而不覆盖现有文件。

不在 workspace 中的内容

这些文件位于 ~/.openclaw/ 下，不应提交到 workspace 仓库：

  • ~/.openclaw/openclaw.json（配置）
  • ~/.openclaw/credentials/（OAuth token、API 密钥）
  • ~/.openclaw/agents/<agentId>/sessions/（session 记录 + 元数据）
  • ~/.openclaw/skills/（托管的 skill）

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

Git 备份（推荐，私有）

把 workspace 当作私密记忆。将它放在一个私有 git 仓库中，这样就能备份和恢复。

在运行 Gateway 的机器上执行这些步骤（workspace 就在那里）。

1) 初始化仓库

如果安装了 git，全新的 workspace 会自动初始化。如果这个 workspace 还不是仓库，运行：

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"

2) 添加私有远程仓库（新手友好选项）

选项 A：GitHub 网页界面

  1. 在 GitHub 上创建一个新的私有仓库。
  2. 不要用 README 初始化（避免合并冲突）。
  3. 复制 HTTPS 远程 URL。
  4. 添加远程仓库并推送：
git branch -M main
git remote add origin <https-url>
git push -u origin main

选项 B：GitHub CLI (gh)

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

选项 C：GitLab 网页界面

  1. 在 GitLab 上创建一个新的私有仓库。
  2. 不要用 README 初始化（避免合并冲突）。
  3. 复制 HTTPS 远程 URL。
  4. 添加远程仓库并推送：
git branch -M main
git remote add origin <https-url>
git push -u origin main

3) 日常更新

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

不要提交密钥

即使在私有仓库中，也要避免在 workspace 中存储密钥：

  • API 密钥、OAuth token、密码或私有凭证。
  • ~/.openclaw/ 下的任何内容。
  • 聊天记录或敏感附件的原始转储。

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

建议的 .gitignore 起始模板：

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

将 workspace 迁移到新机器

  1. 将仓库克隆到所需路径（默认 ~/.openclaw/workspace）。
  2. 在 ~/.openclaw/openclaw.json 中将 agents.defaults.workspace 设置为该路径。
  3. 运行 openclaw setup --workspace <path> 来生成任何缺失的文件。
  4. 如果你需要 session，从旧机器单独复制 ~/.openclaw/agents/<agentId>/sessions/。

高级说明

  • 多 agent routing 可以为每个 agent 使用不同的 workspace。查看 Channel routing 了解 routing 配置。
  • 如果启用了 agents.defaults.sandbox，非主 session 可以使用 agents.defaults.sandbox.workspaceRoot 下的单独 session sandbox workspace。