Agent workspace

workspace 是 agent 的“家”。它是文件类工具与 workspace context 使用的唯一工作目录。 请保持私密，并把它当作 memory 来对待。

这与 ~/.openclaw/ 不同，后者用于存放配置、凭据与 sessions。

**重要：**workspace 是默认 cwd，而不是硬沙箱（hard sandbox）。工具会将相对路径解析到 workspace 内，但除非启用 sandboxing，否则绝对路径仍可能访问主机上的其他位置。 如果你需要隔离，请使用 agents.defaults.sandbox（以及/或按 agent 的 sandbox 配置）。 当启用 sandboxing 且 workspaceAccess 不是 "rw" 时，工具会在 ~/.openclaw/sandboxes 下的 sandbox workspace 内运行，而不是在主机 workspace 上。

默认位置

• 默认：~/clawd
• 如果设置了 openclaw_PROFILE 且不为 "default"，默认会变为 ~/clawd-<profile>。
• 在 ~/.openclaw/moltbot.json 中覆盖：

{
  agent: {
    workspace: "~/clawd"
  }
}

moltbot onboard、moltbot configure 或 moltbot setup 会在 workspace 缺失时创建它，并在 bootstrap files 缺失时写入初始模板。

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

{ agent: { skipBootstrap: true } }

额外的 workspace 文件夹

旧版本安装可能创建过 ~/moltbot。保留多个 workspace 目录可能导致困惑的鉴权或状态漂移，因为任意时刻只会有一个 workspace 处于激活状态。

**建议：**只保留一个活跃 workspace。若你已不再使用额外目录，建议归档或移到回收站（例如 trash ~/moltbot）。 若你有意保留多个 workspaces，请确保 agents.defaults.workspace 指向当前活跃的那一个。

moltbot doctor 在检测到额外 workspace 目录时会给出警告。

Workspace 文件映射（每个文件的含义）

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

• AGENTS.md

  • Agent 的操作说明，以及它应如何使用 memory。
  • 每个 session 开始时加载。
  • 适合放规则、优先级与“应如何表现”的细节。

• SOUL.md

  • Persona、语气与边界。
  • 每个 session 加载。

• USER.md

  • 用户是谁，以及如何称呼。
  • 每个 session 加载。

• IDENTITY.md

  • Agent 的名称、氛围与 emoji。
  • 在 bootstrap 仪式中创建/更新。

• TOOLS.md

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

• HEARTBEAT.md

  • 可选的 heartbeat runs 小清单。
  • 尽量短，以避免 token 消耗。

• BOOT.md

  • 可选的启动清单：当启用 internal hooks 时，在 gateway 重启时执行。
  • 保持简短；对外发送请用 message 工具。

• BOOTSTRAP.md

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

• memory/YYYY-MM-DD.md

  • 每日 memory 日志（每天一个文件）。
  • 建议 session start 时读取今天 + 昨天。

• MEMORY.md（可选）

  • 经过整理的长期记忆。
  • 只会在主私聊 session 中加载（不会在共享/群聊上下文中加载）。

workflow 与自动 memory flush 参见 Memory。

• skills/（可选）

  • workspace 专用 skills。
  • 同名时会覆盖 managed/bundled skills。

• canvas/（可选）

  • 用于 node displays 的 Canvas UI 文件（例如 canvas/index.html）。

如果任何 bootstrap file 缺失，Moltbot 会向 session 注入一条 “missing file” 标记并继续运行。 注入时，大型 bootstrap files 会被截断；可用 agents.defaults.bootstrapMaxChars（默认：20000）调整上限。 moltbot setup 可以在不覆盖现有文件的情况下重新生成缺失的默认文件。

哪些内容不在 workspace 里

这些内容位于 ~/.openclaw/ 下，并且不应提交到 workspace 的仓库：

• ~/.openclaw/moltbot.json（配置）
• ~/.openclaw/credentials/（OAuth tokens、API keys）
• ~/.openclaw/agents/<agentId>/sessions/（session transcripts + 元数据）
• ~/.openclaw/skills/（managed skills）

如果你需要迁移 sessions 或 config，请单独复制它们，并让它们远离版本控制。

Git 备份（推荐，私有）

把 workspace 当作私密记忆，放入一个 私有 git 仓库进行备份与恢复。

请在运行 Gateway 的机器上执行以下步骤（workspace 就在那台机器上）。

1) 初始化仓库

如果安装了 git，全新 workspace 通常会自动初始化为仓库。如果此 workspace 还不是 repo，可以运行：

cd ~/clawd
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 web UI

1. 在 GitHub 创建一个新的 私有仓库。
2. 不要初始化 README（避免 merge 冲突）。
3. 复制 HTTPS remote URL。
4. 添加远端并 push：

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 clawd-workspace --private --source . --remote origin --push

选项 C：GitLab web UI

1. 在 GitLab 创建一个新的 私有仓库。
2. 不要初始化 README（避免 merge 冲突）。
3. 复制 HTTPS remote URL。
4. 添加远端并 push：

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

不要提交 secrets

即使是私有仓库，也应避免把 secrets 放到 workspace 中：

• API keys、OAuth tokens、密码或私密凭据。
• ~/.openclaw/ 下的任何内容。
• 原始聊天导出或敏感附件的原文 dump。

如果必须存放敏感引用，请使用占位符，并把真实 secret 放到其他位置（密码管理器、环境变量或 ~/.openclaw/）。

建议的 .gitignore 起步模板：

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

将 workspace 迁移到新机器

1. 把 repo clone 到期望路径（默认 ~/clawd）。
2. 在 ~/.openclaw/moltbot.json 中把 agents.defaults.workspace 指向该路径。
3. 运行 moltbot setup --workspace <path> 以补齐缺失文件。
4. 若需要 sessions，请从旧机器单独复制 ~/.openclaw/agents/<agentId>/sessions/。

高级备注

• multi-agent routing 可以为不同 agent 使用不同 workspaces。路由配置参见 Channel routing。
• 如果启用了 agents.defaults.sandbox，non-main sessions 可以在 agents.defaults.sandbox.workspaceRoot 下使用 per-session sandbox workspaces。