智能体工作区

工作区是代理的家：用于文件工具和工作区上下文的工作目录。请保持其私密性，并将其视为记忆。

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

默认位置¶

• 默认位置：~/.openclaw/workspace
• 如果设置了 OPENCLAW_PROFILE 且不是 "default"，默认位置将变为 ~/.openclaw-<profile>/workspace。
• 设置 OPENCLAW_WORKSPACE_DIR 后，它将覆盖以上两者。
• 非默认的 OPENCLAW_STATE_DIR 会将默认工作区保持在 <state-dir>/workspace，包括计划维护和初始 main 代理条目。
• 唯一配置的代理会继承默认工作区，除非其条目设置了 workspace。
• 在明确的多代理名册中，未设置 workspace 的条目在配置了该根目录时使用 <agents.defaults.workspace>/<agentId>，否则使用 <state-dir>/workspace-<agentId>。指定共享根目录并不会将其分配给某个代理。

在 ~/.openclaw/openclaw.json 中覆盖：

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

按代理覆盖：agents.entries.*.workspace。要在多代理名册中将 main 保留在现有的共享根目录，请显式地将 agents.entries.main.workspace 固定到该根目录；仅更改 agents.defaults.workspace 会为未固定的条目设置基础目录。

运行工作区选择会拒绝显式提供的空白或无效代理 ID。省略选择器以使用已配置的所有权，或提供预期的代理 ID。

openclaw onboard、openclaw configure 或 openclaw setup 会创建工作区，并在缺少引导文件时填充这些文件。

如果您自己管理工作区文件，请禁用引导文件的创建：

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

额外工作区文件夹¶

较旧的安装可能会创建 ~/openclaw。每个代理使用一个解析出的工作区；保留额外的目录不会将其人格或记忆文件合并到当前工作区中。

工作区文件映射¶

在 Control UI 中使用 Settings → Agents → Files 来编辑这些文件。Preview 显示当前草稿；Edit 返回编辑器以便继续输入，而 Close 则返回 Preview。

OpenClaw 期望在工作区内存在的标准文件：

工作区中不包含的内容¶

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

• ~/.openclaw/openclaw.json（配置）
• ~/.openclaw/state/openclaw.sqlite（共享的工作区设置状态和证明）
• ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite（模型认证配置文件、路由状态、常驻意图、会话行、转录记录、记忆索引状态，以及其他按代理的持久化运行时状态）
• ~/.openclaw/agents/<agentId>/agent/codex-home/（每个代理的 Codex 运行时账户、配置、技能、插件和原生线程状态）
• ~/.openclaw/credentials/（渠道/提供方状态以及旧版 OAuth 导入数据）
• ~/.openclaw/agents/<agentId>/sessions/（旧版迁移来源和存档/支持工件）
• ~/.openclaw/skills/（受管技能）

如果需要迁移会话或配置，请单独复制它们，并确保它们不被纳入版本控制。

较旧版本的 OpenClaw 会写入 openclaw-workspace-state.json、.openclaw/workspace-state.json 和 .attested 工作区 sidecar 文件。当前运行时仅使用共享的 SQLite 数据库来存储该状态。如果 Doctor 报告了这些文件中的某一个，请运行 openclaw doctor --fix；Doctor 会导入有效的旧版状态，并且只有在验证数据库行之后才会删除源文件。workspace-attestations/ 下空的保留哈希文件会被丢弃，因为它们不包含可导入的状态；其他无法读取的源文件会保留在原处，Doctor 会列出它们的路径。

Git 备份（推荐，私有）{#git-backup-recommended-private}¶

将工作区视为私人记忆。把它放在一个 私有 git 仓库中，以便进行备份和恢复。

请在运行 Gateway 的机器上执行这些步骤（工作区就位于该机器上）。

1. 初始化仓库

如果已安装 git，全新的工作区会自动初始化。如果此工作区还不是仓库，请运行：

cd ~/.openclaw/workspace
git init
git add AGENTS.md SOUL.md IDENTITY.md USER.md memory/
git commit -m "Add agent workspace"

2. 添加一个私有远程仓库

git branch -M main
git remote add origin <https-url>
git push -u origin main

gh auth login
gh repo create openclaw-workspace --private --source . --remote origin --push

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

不要提交机密信息¶

建议的 .gitignore 起步模板：

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

将工作区迁移到新机器¶

1. 克隆仓库

将仓库克隆到目标路径（默认 ~/.openclaw/workspace）。

2. 更新配置

在 ~/.openclaw/openclaw.json 中，为应使用该工作区的代理将 agents.entries.<agentId>.workspace 设置为克隆路径。如果没有按代理覆盖的单独代理，则可以使用 agents.defaults.workspace 替代；在多代理名单中，该设置只会更改未固定条目的基础目录。

3. 验证工作区

在启动 Gateway 之前，运行 openclaw agents list 并确认目标代理指向克隆路径。移动现有工作区不需要重新运行引导流程。

4. 复制会话（可选）

如果需要会话，请从旧机器上单独复制 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。仅当您还需要旧版迁移输入或存档/支持工件时，才复制 ~/.openclaw/agents/<agentId>/sessions/。

高级说明¶

• 多代理路由可以通过 agents.entries.*.workspace 为每个代理使用不同的工作区。有关路由配置，请参阅 Channel routing。
• 如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的按会话沙盒工作区。

相关¶

• Backups - 存档、按数据库快照、调度以及状态和工作区的异地副本
• Bootstrapping - 首次运行流程，用于初始化新工作区及其身份文件
• Default AGENTS.md - 放置在工作区中的默认代理指令和技能列表
• Heartbeat - 心跳监视和 cron 暂存区
• Sandboxing - 沙盒环境中的工作区访问
• Session - 会话存储路径
• Standing orders - 工作区文件中的持久指令
• System prompt - 将工作区文件注入到提示词中的位置