智能体工作区

工作区是智能体的家。它是文件工具和工作区上下文使用的唯一工作目录。保持私密并将其视为内存?

这与 ~/.openclaw/ 不同，后者存储配置、凭据和会话?

*重要? 工作区是默认 cwd，而不是硬沙盒。工具相对于工作区解析相对路径，但如果未启用沙盒，绝对路径仍然可以访问主机上的其他位置。如果需要隔离，请使?agents.defaults.sandbox（和/或每个智能体的沙盒配置）? 启用沙盒?workspaceAccess 不是 "rw" 时，工具?~/.openclaw/sandboxes 下的沙盒工作区内操作，而不是你的主机工作区?

默认位置

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

openclaw onboard、openclaw configure ?openclaw setup 将创建工作区并在缺失时植入引导文件?

如果你已经自己管理工作区文件，可以禁用引导文件创建：

{ agent: { skipBootstrap: true } }

额外工作区文件夹

旧安装可能创建了 ~/openclaw。保留多个工作区目录会导致混乱的认证或状态漂移，因为一次只有一个工作区是活动的?

*建议? 保持单一活动工作区。如果你不再使用额外文件夹，请将它们存档或移到垃圾箱（例?trash ~/openclaw）? 如果你故意保留多个工作区，请确保 agents.defaults.workspace 指向活动的工作区?

openclaw doctor 在检测到额外工作区目录时发出警告?

工作区文件映射（每个文件的含义）

这些?OpenClaw 在工作区内期望的标准文件?

  • AGENTS.md

    • 智能体的操作说明以及它应该如何使用内存?
    • 在每个会话开始时加载?
    • 是放置规则、优先级?如何行为”细节的好地方?

  • SOUL.md

    • 人设、语气和边界?
    • 每个会话加载?

  • USER.md

    • 用户是谁以及如何称呼他们?
    • 每个会话加载?

  • IDENTITY.md

    • 智能体的名称、风格和表情符号?
    • 在引导仪式期间创?更新?

  • TOOLS.md

    • 关于本地工具和约定的笔记?
    • 不控制工具可用性；它只是指导?

  • HEARTBEAT.md

    • 心跳运行的可选微小检查清单?
    • 保持简短以避免令牌消耗?

  • BOOT.md

    • 网关重启时在内部钩子启用时执行的可选启动检查清单?
    • 保持简短；使用消息工具进行出站发送?

  • BOOTSTRAP.md

    • 一次性首次运行仪式?
    • 仅为全新工作区创建?
    • 仪式完成后删除?

  • memory/YYYY-MM-DD.md

    • 每日内存日志（每天一个文件）?
    • 建议在会话开始时读取今天和昨天?

  • MEMORY.md（可选）

    • 精选的长期内存?
    • 仅在主会话、私人会话中加载（不是共?群组上下文）?

参见 Memory 了解工作流和自动内存刷新?

  • skills/（可选）

    • 工作区特定的技能?
    • 当名称冲突时覆盖托管/捆绑技能?

  • canvas/（可选）

    • 节点显示?Canvas UI 文件（例?canvas/index.html）?

如果任何引导文件缺失，OpenClaw 会将”缺失文件”标记注入会话并继续。大型引导文件在注入时被截断? 使用 agents.defaults.bootstrapMaxChars（默认：20000）和 agents.defaults.bootstrapTotalMaxChars（默认：150000）调整限制? openclaw setup 可以重新创建缺失的默认值而不会覆盖现有文件?

什么不在工作区?

这些位于 ~/.openclaw/ 下，不应提交到工作区仓库?

  • ~/.openclaw/openclaw.json（配置）
  • ~/.openclaw/credentials/（OAuth 令牌、API 密钥?
  • ~/.openclaw/agents/<agentId>/sessions/（会话记录和元数据）
  • ~/.openclaw/skills/（托管技能）

如果你需要迁移会话或配置，请单独复制它们并保持在版本控制之外?

Git 备份（推荐，私有?

将工作区视为私有内存。将其放?私有* git 仓库中，以便备份和可恢复?

在运行网关的机器上执行这些步骤（那是工作区所在的地方）?

1) 初始化仓?

如果安装?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"

2) 添加私有远程（适合初学者）

选项 A：GitHub Web UI

  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 Web UI

  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

不要提交密钥

即使在私有仓库中，也要避免在工作区中存储密钥?

  • API 密钥、OAuth 令牌、密码或私人凭据?
  • ~/.openclaw/ 下的任何内容?
  • 聊天或敏感附件的原始转储?

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

建议?.gitignore 入门?

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

将工作区移动到新机器

  1. 将仓库克隆到 desired 路径（默?~/.openclaw/workspace）?
  2. ?~/.openclaw/openclaw.json 中将 agents.defaults.workspace 设置为该路径?
  3. 运行 openclaw setup --workspace <path> 以植入任何缺失的文件?
  4. 如果需要会话，请单独从旧机器复?~/.openclaw/agents/<agentId>/sessions/?

高级说明

  • 多智能体路由可以为每个智能体使用不同的工作区。参? 频道路由 了解路由配置?
  • 如果 agents.defaults.sandbox 启用，非主会话可以使?agents.defaults.sandbox.workspaceRoot 下每个会话的沙盒工作区?