openclaw/docs/zh-CN/concepts/agent-workspace.md

read_when, summary, title, x-i18n

read_when	summary	title	x-i18n
你需要解释智能体工作区或其文件布局 你想要备份或迁移智能体工作区	智能体工作区：位置、布局和备份策略	智能体工作区	generated_at model provider source_hash source_path workflow 2026-02-01T20:22:05Z claude-opus-4-5 pi 84c550fd89b5f2474aeae586795485fd29d36effbb462f13342b31540fc18b82 concepts/agent-workspace.md 14

智能体工作区

工作区是智能体的主目录。它是文件工具和工作区上下文使用的唯一工作目录。请将其保持私密，并视为记忆来对待。

它与 ~/.openclaw/ 是分开的，后者存储配置、凭据和会话。

重要提示： 工作区是默认工作目录，而非硬性沙箱。工具会基于工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置，除非启用了沙箱。如果你需要隔离，请使用 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

  • 可选的启动清单，在启用内部钩子时于 Gateway网关重启时执行。
  • 保持简短；使用消息工具进行外发。

• BOOTSTRAP.md

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

• memory/YYYY-MM-DD.md

  • 每日记忆日志（每天一个文件）。
  • 建议在会话开始时读取今天和昨天的内容。

• MEMORY.md（可选）

  • 精选的长期记忆。
  • 仅在主要的私人会话中加载（不在共享/群组上下文中）。

参见记忆了解工作流程和自动记忆刷写。

• skills/（可选）

  • 工作区特定的 Skills。
  • 名称冲突时覆盖托管/内置 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/（会话记录和元数据）
• ~/.openclaw/skills/（托管 Skills）

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

Git 备份（推荐，私有）

将工作区视为私有记忆。将其放入一个私有 git 仓库中，以便备份和恢复。

在 Gateway网关运行的机器上执行以下步骤（工作区就在那里）。

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 网页界面

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

不要提交密钥

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

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

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

建议的 .gitignore 起始内容：

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

将工作区迁移到新机器

1. 将仓库克隆到目标路径（默认 ~/.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 下的按会话沙箱工作区。