代理工作区
代理工作区：位置、布局和备份策略
工作空间是代理的家。它是唯一用于
文件工具和工作区上下文。保持其私密性并将其视为内存。
这与 ''~/.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''（可选）
- 精心策划的长期记忆。
- 仅在主私有会话中加载（不是共享/组上下文）。
有关工作流程和自动内存刷新，请参阅''内存''。
- ''skills/''（可选）
- 工作场所特定技能。
- 当名称冲突时覆盖托管/捆绑技能。
- ''canvas/''（可选）
- 用于节点显示的 Canvas UI 文件（例如 ''canvas/index.html''）。
如果缺少任何引导文件，OpenClaw 会在其中注入"丢失文件"标记
会议并继续。注入时大型引导文件会被截断；
使用 ''agents.defaults.bootstrapMaxChars'' 调整限制（默认值：20000）。
''openclaw setup'' 可以重新创建缺失的默认值而不覆盖现有的
文件。
工作区中不存在的内容
这些位于 ''~/.openclaw/'' 下，不应提交到工作区存储库：
- ''~/.openclaw/openclaw.json''（配置）
- ''~/.openclaw/credentials/''（OAuth 令牌、API 密钥）
- ''~/.openclaw/agents/<agentId>/sessions/'' (session logs + metadata)
- ''~/.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. 将存储库克隆到所需路径（默认 ''~/.openclaw/workspace''）。
2. 将 ''agents.defaults.workspace'' 设置为 ''~/.openclaw/openclaw.json'' 中的该路径。
3. Run ''openclaw setup --workspace <path>'' to seed any missing files.
4. If you need sessions, copy ''~/.openclaw/agents/<agentId>/sessions/'' from the
旧机单独。
高级注释
- 多代理路由可以为每个代理使用不同的工作区。参见
''通道路由'' 用于路由配置。
- 如果启用 ''agents.defaults.sandbox''，非主会话可以使用每会话沙箱
''agents.defaults.sandbox.workspaceRoot'' 下的工作区。