Agent 工作区

工作区是 agent 的家。文件工具和工作区上下文都在这里运行，它是唯一的工作目录。把它当作 agent 的记忆来对待，注意保密。

工作区和 ~/.openclaw/ 是分开的，后者存放配置、凭证和会话数据。

注意： 工作区是默认工作目录，不是硬性沙箱。工具会基于工作区解析相对路径，但绝对路径仍然可以访问主机上的其他位置——除非开启了沙箱模式。如果你需要隔离，请使用 agents.defaults.sandbox（也可以配合每个 agent 的沙箱配置）。开启沙箱且 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 会创建工作区并初始化 bootstrap 文件（如果缺失的话）。沙箱种子复制只接受工作区内的常规文件；指向工作区外部的符号链接/硬链接会被忽略。

如果你已经自己管理工作区文件，可以禁用 bootstrap 文件的自动创建：

{ agent: { skipBootstrap: true } }

多余的工作区目录

旧版安装可能创建过 ~/openclaw。同时存在多个工作区目录容易导致认证或状态不一致，因为同一时间只有一个工作区是活跃的。

建议： 只保留一个活跃工作区。如果不再使用多余的目录，可以归档或移到回收站（比如 trash ~/openclaw）。如果你确实需要保留多个工作区，确保 agents.defaults.workspace 指向当前活跃的那个。

openclaw doctor 会在检测到多余工作区目录时发出警告。

工作区文件说明

OpenClaw 在工作区中预期的标准文件：

  • AGENTS.md

    • agent 的操作指令，以及如何使用记忆。
    • 每次会话开始时加载。
    • 适合放规则、优先级和行为准则。

  • SOUL.md

    • 人设、语气和边界。
    • 每次会话加载。

  • USER.md

    • 用户是谁，以及如何称呼。
    • 每次会话加载。

  • IDENTITY.md

    • agent 的名字、风格和 emoji。
    • 在 bootstrap 仪式中创建/更新。

  • TOOLS.md

    • 关于本地工具和使用惯例的备注。
    • 不控制工具的可用性，只是指导。

  • HEARTBEAT.md

    • 可选的心跳运行检查清单。
    • 尽量简短，避免浪费 token。

  • BOOT.md

    • 可选的启动检查清单，Gateway 重启且内部 hook 启用时执行。
    • 尽量简短；发送消息请使用 message 工具。

  • BOOTSTRAP.md

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

  • memory/YYYY-MM-DD.md

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

  • MEMORY.md（可选）

    • 经过整理的长期记忆。
    • 只在主会话（私人会话）中加载，不要在共享/群组上下文中加载。

详见 记忆。

  • skills/（可选）

    • 工作区专属 skills。
    • 名称冲突时会覆盖托管/内置 skills。

  • canvas/（可选）

    • Canvas UI 文件，用于节点展示（比如 canvas/index.html）。

如果任何 bootstrap 文件缺失，OpenClaw 会在会话中注入一个”文件缺失”标记，然后继续运行。大型 bootstrap 文件在注入时会被截断；可以通过 agents.defaults.bootstrapMaxChars（默认 20000）和 agents.defaults.bootstrapTotalMaxChars（默认 150000）调整限制。openclaw setup 可以重新创建缺失的默认文件，不会覆盖已有文件。

不在工作区中的内容

以下内容存放在 ~/.openclaw/ 下，不要提交到工作区仓库：

  • ~/.openclaw/openclaw.json（配置）
  • ~/.openclaw/credentials/（OAuth token、API key）
  • ~/.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 远程地址。
  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 远程地址。
  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 key、OAuth token、密码或私有凭证。
  • ~/.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/。

进阶说明

  • 多 agent 路由可以为每个 agent 使用不同的工作区。详见 通道路由。
  • 如果启用了 agents.defaults.sandbox，非主会话可以使用 agents.defaults.sandbox.workspaceRoot 下的每会话沙箱工作区。
arrow_back
上一页
Context
下一页
OAuth
arrow_forward