跳转到内容
OpenClaw Docs

Agent 的工作区

工作区是 Agent 的主目录。它是用于文件工具和工作区上下文的唯一工作目录。请保持其私密性，并将其视为记忆。

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

默认位置

Section titled “默认位置”
  • 默认值：~/.openclaw/workspace
  • 如果设置了 OPENCLAW_PROFILE 且不为 "default"，则默认值变为 ~/.openclaw/workspace-<profile>。
  • 在 ~/.openclaw/openclaw.json 中覆盖：
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

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

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

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

额外的工作区文件夹

Section titled “额外的工作区文件夹”

较旧的安装可能创建了 ~/openclaw。保留多个工作区目录可能会导致身份验证或状态漂移的混淆，因为同一时间只有一个工作区是活动的。

工作区文件映射

Section titled “工作区文件映射”

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

AGENTS.md - operating instructions

代理的操作说明及其应如何使用记忆。在每次会话开始时加载。适合用于放置规则、优先级和“如何表现”的细节。

SOUL.md - persona and tone

个性、语调和边界。每个会话加载。指南：SOUL.md personality guide。

USER.md - who the user is

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

IDENTITY.md - name, vibe, emoji

代理的名称、氛围和表情符号。在启动仪式期间创建/更新。

TOOLS.md - local 工具 conventions

关于您的本地工具和约定的说明。这不控制工具的可用性；它仅作为指导。

HEARTBEAT.md - heartbeat checklist

用于心跳运行的可选微型检查清单。保持简短以避免消耗 token。

BOOT.md - startup checklist

在网关重启时自动运行的可选启动检查清单（当启用 internal hooks 时）。保持简短；使用消息工具进行对外发送。

BOOTSTRAP.md - 首次运行仪式

一次性首次运行仪式。仅为全新的工作区创建。仪式完成后将其删除。

memory/YYYY-MM-DD.md - 每日记忆日志

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

MEMORY.md - 精选长期记忆（可选）

精选长期记忆：持久化的事实、偏好、决策和简短摘要。将详细日志保存在 memory/YYYY-MM-DD.md 中，以便记忆工具可以按需检索它们，而无需将它们注入到每个提示中。仅应在主要的私人会话（而非共享/群组上下文）中加载 MEMORY.md。有关工作流程和自动内存刷新，请参阅 Memory。

skills/ - 工作区技能（可选）

特定于工作区的技能。该工作区的最高优先级技能位置。当名称冲突时，覆盖项目代理技能、个人代理技能、托管技能、捆绑技能和 skills.load.extraDirs。

Canvascanvas/ - Canvas UI 文件（可选）

用于节点显示的 Canvas UI 文件（例如 canvas/index.html）。

工作区中不存在的内容

Section titled “工作区中不存在的内容”

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

  • ~/.openclaw/openclaw.json（配置）
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (模型身份验证配置：OAuth + API 密钥)
  • ~/.openclaw/agents/<agentId>/agent/codex-home/ (每个代理的 Codex 运行时账户、配置、技能、插件和原生线程状态)
  • ~/.openclaw/credentials/ (渠道/提供商状态以及旧版 OAuth 导入数据)
  • ~/.openclaw/agents/<agentId>/sessions/ (会话记录 + 元数据)
  • ~/.openclaw/skills/ (托管技能)

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

Git 备份（推荐，私有）

Section titled “Git 备份（推荐，私有）”

将工作区视为私有内存。将其放在一个 私有 git 仓库中，以便进行备份和恢复。

在运行 Gateway(网关) 的机器上运行这些步骤（那是工作区所在的位置）。

  1. 初始化仓库

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

    Terminal window
    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. 添加私有远程仓库

    1. 在 GitHub 上创建一个新的 私有 仓库。
    2. 不要使用 README 初始化（避免合并冲突）。
    3. 复制 HTTPS 远程 URL。
    4. 添加远程仓库并推送：
    Terminal window
    git branch -M main
    git remote add origin

    git push -u origin main

  3. 后续更新

    Terminal window
    git status
    git add .
    git commit -m "Update memory"
    git push

不要提交机密信息

Section titled “不要提交机密信息”

建议的 .gitignore 入门文件：

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

将工作区移动到新机器

Section titled “将工作区移动到新机器”

  1. 克隆仓库

    将仓库克隆到所需路径（默认为 ~/.openclaw/workspace）。

  2. 更新配置

    在 ~/.openclaw/openclaw.json 中将 agents.defaults.workspace 设置为该路径。

  3. 补充缺失文件

    运行 `openclaw setup —workspace

    ` 以补充任何缺失的文件。

  4. 复制会话（可选）

    如果您需要会话，请单独从旧机器复制 `~/.openclaw/agents/

    /sessions/`。

高级说明

Section titled “高级说明”
  • 多代理路由可以为每个代理使用不同的工作区。有关路由配置，请参阅通道路由。
  • 如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的每会话沙箱工作区。

相关内容

Section titled “相关内容”