ClawCN - OpenClaw 中文版

主题

Agent 工作空间 ​

工作空间是 agent 的家。它是文件工具和工作空间上下文使用的唯一工作目录。请保持私密并将其视为内存。

这与 ~/.openclaw/ 是分开的,后者用于存储配置、凭证和会话。

重要提示:工作空间是默认的 cwd,而不是硬沙箱。工具会相对于工作空间解析相对路径,但绝对路径仍然可以访问主机上的其他位置,除非启用了沙箱。如果需要隔离,请使用 agents.defaults.sandbox(和/或每个 agent 的沙箱配置)。当启用沙箱且 workspaceAccess 不是 "rw" 时,工具会在 ~/.openclaw/sandboxes 下的沙箱工作空间内操作,而不是您的主机工作空间。

默认位置 ​

  • 默认:~/.openclaw/workspace
  • 如果设置了 OPENCLAW_PROFILE 且不是 "default",默认位置将变为 ~/.openclaw/workspace-<profile>。
  • 在 ~/.openclaw/openclaw.json 中覆盖:
json5
{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

openclaw onboard、openclaw configure 或 openclaw setup 会创建工作空间并在缺少引导文件时生成它们。

如果您已经自己管理工作空间文件,可以禁用引导文件创建:

json5
{ agent: { skipBootstrap: true } }

额外的工作空间文件夹 ​

旧的安装可能创建了 ~/openclaw。保留多个工作空间目录可能会导致令人困惑的认证或状态漂移,因为一次只有一个工作空间处于活动状态。

**建议:**保留一个活动的工作空间。如果您不再使用额外的文件夹,请将它们归档或移至废纸篓(例如 trash ~/openclaw)。如果您有意保留多个工作空间,请确保 agents.defaults.workspace 指向活动的那个。

openclaw doctor 会在检测到额外的工作空间目录时发出警告。

工作空间文件映射(每个文件的含义) ​

这些是 OpenClaw 在工作空间内预期的标准文件:

  • AGENTS.md

    • agent 的操作说明以及应如何使用内存。
    • 在每次会话开始时加载。
    • 适合放置规则、优先级和"行为方式"细节。

  • SOUL.md

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

  • USER.md

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

  • IDENTITY.md

    • agent 的名称、氛围和表情符号。
    • 在引导仪式期间创建/更新。

  • TOOLS.md

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

  • HEARTBEAT.md

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

  • BOOT.md

    • 当启用内部钩子时,在网关重启时执行的可选启动检查清单。
    • 保持简短;使用消息工具进行出站发送。

  • BOOTSTRAP.md

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

  • memory/YYYY-MM-DD.md

    • 每日内存日志(每天一个文件)。
    • 建议在会话开始时读取今天+昨天的日志。

  • MEMORY.md(可选)

    • 精选的长期内存。
    • 仅在主要的私密会话中加载(不在共享/群组上下文中)。

有关工作流程和自动内存刷新,请参见内存。

  • 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/(托管技能)

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

Git 备份(推荐,私有) ​

将工作空间视为私有内存。将其放入私有 git 仓库,以便进行备份和恢复。

在运行 Gateway 的机器上运行以下步骤(工作空间所在位置)。

1) 初始化仓库 ​

如果安装了 git,全新的工作空间会自动初始化。如果此工作空间还不是仓库,请运行:

bash
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 Web UI

  1. 在 GitHub 上创建一个新的私有仓库。
  2. 不要使用 README 初始化(避免合并冲突)。
  3. 复制 HTTPS 远程 URL。
  4. 添加远程仓库并推送:
bash
git branch -M main
git remote add origin <https-url>
git push -u origin main

选项 B:GitHub CLI(gh)

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

选项 C:GitLab Web UI

  1. 在 GitLab 上创建一个新的私有仓库。
  2. 不要使用 README 初始化(避免合并冲突)。
  3. 复制 HTTPS 远程 URL。
  4. 添加远程仓库并推送:
bash
git branch -M main
git remote add origin <https-url>
git push -u origin main

3) 持续更新 ​

bash
git status
git add .
git commit -m "Update memory"
git push

不要提交密钥 ​

即使在私有仓库中,也要避免在工作空间中存储密钥:

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

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

建议的 .gitignore 起始配置:

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 下的每会话沙箱工作空间。