OpenClaw从入门到应用——Agent：工作空间（Workspace）
通过OpenClaw实现副业收入：《OpenClaw赚钱实录：从“养龙虾“到可持续变现的实践指南》
Agent workspace
工作空间是代理的家。它是用于文件工具和工作空间上下文的唯一工作目录。请将其视为私有内存并妥善保管。这与存储配置、凭证和会话的~/.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）。
- 用于节点显示的 Canvas UI 文件（例如
如果任何引导文件缺失，OpenClaw 会向会话中注入一个“文件缺失”标记并继续。大型引导文件在注入时会被截断；可通过agents.defaults.bootstrapMaxChars（默认：20000）和agents.defaults.bootstrapTotalMaxChars（默认：150000）调整限制。openclaw setup可以在不覆盖现有文件的情况下重新创建缺失的默认文件。
不在工作空间中的内容
以下内容位于~/.openclaw/下，不应提交到工作空间仓库：
~/.openclaw/openclaw.json（配置）~/.openclaw/credentials/（OAuth 令牌、API 密钥）~/.openclaw/agents/<agent-id>/sessions/（会话记录 + 元数据）~/.openclaw/skills/（托管技能）
如果需要迁移会话或配置，请单独复制它们并使其脱离版本控制。
Git 备份（推荐，私有）
将工作空间视为私有内存。将其放入一个私有git 仓库中，以便备份和恢复。请在运行网关的机器上执行以下步骤（即工作空间所在的位置）。
1) 初始化仓库
如果已安装 git，全新的工作空间会自动初始化。如果此工作空间还不是一个仓库，请运行：
cd~/.openclaw/workspacegitinitgitaddAGENTS.md SOUL.md TOOLS.md IDENTITY.mdUSER.md HEARTBEAT.md memory/gitcommit-m"Add agent workspace"2) 添加私有远程仓库（适合初学者的选项）
选项 A：GitHub Web UI
- 在 GitHub 上创建一个新的私有仓库。
- 不要使用 README 初始化（避免合并冲突）。
- 复制 HTTPS 远程仓库 URL。
- 添加远程仓库并推送：
gitbranch-Mmaingitremoteaddorigin<你的远程URL>gitpush-uorigin main选项 B：GitHub CLI (gh)
gh auth login gh repo create openclaw-workspace--private--source.--remoteorigin--push选项 C：GitLab Web UI
- 在 GitLab 上创建一个新的私有仓库。
- 不要使用 README 初始化（避免合并冲突）。
- 复制 HTTPS 远程仓库 URL。
- 添加远程仓库并推送：
gitbranch-Mmaingitremoteaddorigin<你的远程URL>gitpush-uorigin main3) 持续更新
gitstatusgitadd.gitcommit-m"Update memory"gitpush不要提交机密信息
即使在私有仓库中，也要避免在工作空间中存储机密信息：
- API 密钥、OAuth 令牌、密码或私有凭证。
~/.openclaw/下的任何内容。- 聊天记录或敏感附件的原始转储。
如果必须存储敏感引用，请使用占位符并将真实机密保存在其他地方（密码管理器、环境变量或~/.openclaw/）。建议的.gitignore入门文件：
.DS_Store .env **/*.key **/*.pem **/secrets*将工作空间迁移到新机器
- 将仓库克隆到所需路径（默认为
~/.openclaw/workspace）。 - 在
~/.openclaw/openclaw.json中将agents.defaults.workspace设置为该路径。 - 运行
openclaw setup --workspace <路径>以填充任何缺失的文件。 - 如果需要会话，请从旧机器单独复制
~/.openclaw/agents/<agent-id>/sessions/。
高级说明
- 多代理路由可以为每个代理使用不同的工作空间。有关路由配置，请参阅频道路由。
- 如果启用了
agents.defaults.sandbox，非主会话可以在agents.defaults.sandbox.workspaceRoot下使用每个会话的沙盒工作空间。