OpenClaw Agent Workspace 是智能体的运行目录，默认位于 ~/.openclaw/workspace，通过 Git 私有仓库备份是最佳实践。位置可通过 agents.defaults.workspace 覆盖；迁移时需克隆仓库、更新配置并运行 openclaw setup 补全文件。Workspace 不是硬性沙箱，绝对路径可访问宿主机，需开启沙箱并在 workspaceAccess 配置才受限。

OpenClaw Agent Workspace 配置与迁移指南

Workspace 是智能体的“家”。所有文件工具的读写操作都以它为根目录，工作区上下文也来自这里。把它当成私人记忆来保管。

这和 ~/.openclaw/（存放配置、凭证和会话记录的地方）是分开的。

WARNING

Workspace 是默认的工作目录（cwd），不是硬性沙箱。工具会将相对路径解析到 Workspace，但绝对路径仍然可以访问宿主机的其他位置——除非你开启了沙箱。如果需要隔离，请配置 agents.defaults.sandbox（也可按智能体单独配置）。开启沙箱且 workspaceAccess 不为 "rw" 时，工具将在 ~/.openclaw/sandboxes 下的沙箱 Workspace 中运行，而非你的宿主机 Workspace。

默认位置

• 默认：~/.openclaw/workspace
• 若设置了 OPENCLAW_PROFILE 且不为 "default"，默认变为 ~/.openclaw/workspace-<profile>
• 可在 ~/.openclaw/openclaw.json 中覆盖：

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

执行 openclaw onboard、openclaw configure 或 openclaw setup 时，若 Workspace 不存在，会自动创建并写入引导文件。沙箱的种子复制只接受 Workspace 内的普通文件；解析到 Workspace 之外的符号链接/硬链接会被忽略。

如果你自己管理 Workspace 文件，可以禁用引导文件创建：

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

多余的 Workspace 目录

旧版本安装可能创建过 ~/openclaw。同时保留多个 Workspace 目录会导致认证或状态混乱，因为每次只有一个 Workspace 是活跃的。

TIP

建议： 只保留一个活跃 Workspace。如果不再使用那些多余的目录，请将其归档或移入回收站（例如 trash ~/openclaw）。如果你确实需要多个 Workspace，请确保 agents.defaults.workspace 指向当前活跃的那个。

openclaw doctor 检测到多余的 Workspace 目录时会发出警告。

Workspace 文件说明

以下是 OpenClaw 在 Workspace 内期望找到的标准文件：

• AGENTS.md — 操作指令，以及如何使用记忆的说明。每次会话开始时加载。适合放规则、优先级以及“行为准则”等内容。
• SOUL.md — 角色人设、语气风格与边界限制。每次会话加载。参见 SOUL.md 人设指南。
• USER.md — 用户是谁，以及如何称呼用户。每次会话加载。
• IDENTITY.md — 智能体的名称、气质与 emoji。在引导仪式中创建/更新。
• TOOLS.md — 本地工具和约定的说明。不控制工具可用性，仅作为指导。
• HEARTBEAT.md — 可选的心跳运行小清单。保持简短，避免消耗大量 token。
• BOOT.md — 可选的启动清单，在开启 内部 hooks 时随 Gateway 重启执行。保持简短；通过 message 工具发送外发消息。
• BOOTSTRAP.md — 首次运行的一次性仪式。只为全新 Workspace 创建。仪式完成后请删除。
• memory/YYYY-MM-DD.md — 每日记忆日志（每天一个文件）。建议在会话开始时读取今天和昨天的日志。
• MEMORY.md（可选） — 精心整理的长期记忆：持久的事实、偏好、决策和简短摘要。只在主私人会话中加载（不在共享/群组上下文中加载）。参见 Memory 了解工作流和自动刷新。
• skills/（可选） — Workspace 专属 Skills。同名时覆盖托管/内置 Skills。
• canvas/（可选） — Canvas UI 文件（例如 canvas/index.html）。

如果某个引导文件缺失，OpenClaw 会在会话中注入一个“文件缺失”标记并继续运行。大型引导文件注入时会被截断；可通过 agents.defaults.bootstrapMaxChars（默认：12000）和 agents.defaults.bootstrapTotalMaxChars（默认：60000）调整限制。openclaw setup 可在不覆盖现有文件的前提下重建缺失的默认文件。

不在 Workspace 中的内容

以下文件位于 ~/.openclaw/，不应提交到 Workspace 仓库：

• ~/.openclaw/openclaw.json（配置）
• ~/.openclaw/agents/<agentId>/agent/auth-profiles.json（模型认证配置：OAuth + API 密钥）
• ~/.openclaw/agents/<agentId>/agent/codex-home/（每个智能体的 Codex 运行时账户、配置、Skills、插件和原生线程状态）
• ~/.openclaw/credentials/（渠道/提供者状态及遗留 OAuth 导入数据）
• ~/.openclaw/agents/<agentId>/sessions/（会话记录和元数据）
• ~/.openclaw/skills/（托管 Skills）

如果需要迁移会话或配置，请单独复制，并排除在版本控制之外。

Git 备份（推荐，私有）

把 Workspace 当作私人记忆来对待。将其放入私有 Git 仓库，以便备份和恢复。

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

1. 初始化仓库

如果安装了 git，全新的 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

不要提交敏感信息

WARNING

即使在私有仓库中，也要避免在 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. 如需迁移会话记录，从旧机器单独复制 ~/.openclaw/agents/<agentId>/sessions/。

高级说明

• 多智能体路由可以为每个智能体配置不同的 Workspace。路由配置见 Channel routing。
• 如果 agents.defaults.sandbox 已启用，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的每会话沙箱 Workspace。

常见问题

OpenClaw Workspace 默认路径在哪？怎么修改？

默认路径为 ~/.openclaw/workspace。若设置了环境变量 OPENCLAW_PROFILE 且不为 "default"，则变为 ~/.openclaw/workspace-<profile>。可在 ~/.openclaw/openclaw.json 中通过 agents.defaults.workspace 覆盖任意路径。

Workspace 文件缺失会怎样？怎么重建？

如果某个引导文件缺失，OpenClaw 会在会话中注入“文件缺失”标记并继续运行。运行 openclaw setup 可在不覆盖现有文件的前提下重建缺失的默认文件。大型文件会被截断，可通过 agents.defaults.bootstrapMaxChars（默认12000）和 bootstrapTotalMaxChars（默认60000）调整限制。

如何安全地将 Workspace 迁移到新机器？

将 Git 仓库克隆到新机器默认路径（或自定义路径），更新 agents.defaults.workspace 配置，运行 openclaw setup --workspace <path> 补全缺失文件。如果需要会话记录，单独从旧机器复制 ~/.openclaw/agents/<agentId>/sessions/。避免在 Workspace 中存储任何敏感凭证。